Location of Docs

[Paul Wright]

Hi,

At a meeting a few weeks ago, we decided not to centralize all the docs for mobile.next, because:

* keep docs closer to code

* keep docs and code versioned together

* allow devs update docs in same repo as they are working

We also decided not to create sidecar repos, eg a mobile-<service>-docs repo.

With that in mind, I thought that docs for push would end up in:

https://github.com/aerogear/aerogear-unifiedpush-server

and docs for android sdk would end up in:

https://github.com/aerogear/aerogear-android-sdk

but that was before I discovered that the following is the nearest thing to a 'metrics' repo that would be suitable for /docs:

https://github.com/aerogearcatalog/metrics-apb

However, I don't think switching org is a good experience for anyone (user or contributor), so I'm wondering if anyone has a good idea where to docs should live (relative to the code), eg:

* service and sdk docs live the apb repos

* service docs in apb repos, and sdk docs in 'code' repo

* something else

thanks,

Paul

--

Paul Wright

Senior Technical Writer

Red Hat, Waterford, Ireland

gitlab: finp

[Wojciech Trocki]

We started writing user stories for SDK's (splitting between contributor and user roles )

SDK's already have solid base that will be extended over the time, with similar patterns across platforms.

IOS: 
https://github.com/aerogear/aerogear-ios-sdk/tree/master/docs

 

Android (WIP - going to be updated soon)

https://github.com/aerogear/aerogear-android-sdk/tree/master/docs

> and docs for android sdk would end up in:

https://github.com/aerogear/aerogear-android-sdk/tree/master/docs/push

Android-sdk repository is just used for Mobile OpenShift Service Catalog (AeroGear Services) 

so push SDK may be probably in separate repository and be imported into AeroGear Services SDK.

Regards

Wojtek

--
You received this message because you are subscribed to the Google Groups "Aerogear" group.
To unsubscribe from this group and stop receiving emails from it, send an email to aerogear+unsubscribe@googlegroups.com.
To post to this group, send email to aero...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/aerogear/CALLRKFhFVgDt1KiAiJ1R22qmcP%2Be_%2Bp3g9hbYnrrRoqXFuvKzQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

WOJCIECH TROCKI

Red Hat Mobile

IM: wtrocki

[Jose Miguel Gallas Olmedo]

Hi Paul,

think docs should live into their respective repos (including references and guides) since it's always easier for everyone to find them. Documentation about services in the -apb repos, SDKs in -sdk repos and so on.

At a meeting a few weeks ago, we decided not to centralize all the docs for mobile.next, because:
* keep docs closer to code
* keep docs and code versioned together
* allow devs update docs in same repo as they are working
We also decided not to create sidecar repos, eg a mobile-<service>-docs repo.

 

Assuming we as in we, Aerogear, several of docs from https://github.com/aerogear/mobile-docs/ should be moved into their respective repos.

I however think mobile-docs would be good to have general documentation and how-tos that affects several services or the platform itself like adding-services-to-ansible-broker.adoc.

Regards,

JOSE MIGUEL GALLAS OLMEDO

ASSOCIATE QE, mobile

Red Hat 

M: +34618488633    

To view this discussion on the web visit https://groups.google.com/d/msgid/aerogear/CAO0%2Bn%2BrSV8fD5A4fuTJiKrXoba2MpnXrSB1CLrmV%3DrYgnZ%2BCzA%40mail.gmail.com.

[Paul Wright]

Thanks Jose,

I will follow up and move things appropriately after we agree on the layout.

So what you're saying (and I like it) is:

https://github.com/aerogear:

* mobile-docs

* <sdk>/docs

* mobile-cli/docs

https://github.com/aerogearcatalog

* <service>-apb/docs

I'm assuming that the release tagging for <service>-apb repo is always the 'version number' we want to communicate to end users?

It's unfortunate that it's split over two github organizations, but we can 'fix that in docs' if agreed,

Paul

[Jose Miguel Gallas Olmedo]

So what you're saying (and I like it) is:

@Paul That's correct.

Actually I was thinking if it wouldn't be better to name it mobile-guides (or something similar) instead of mobile-docs? It might be confusing to have so many "docs" around. But I might be wrong, it's just an idea.

I'm assuming that the release tagging for <service>-apb repo is always the 'version number' we want to communicate to end users?

I'm not sure about the tagging but @David might know the answer?

JOSE MIGUEL GALLAS OLMEDO

ASSOCIATE QE, mobile

Red Hat 

M: +34618488633    

[cro...@redhat.com]

Hey guys,

Looking at the proposed layout, I am wondering where would be an appropriate place to store auto-generated docs, like javadoc etc. As it is not common practice to store these in the source repo. If we are following the below layout, where do you think would be the best place to keep the likes of Javadocs. 

[David Martin]

On 13 February 2018 at 11:15, Jose Miguel Gallas Olmedo <jgal...@redhat.com> wrote:

So what you're saying (and I like it) is:

@Paul That's correct.

Actually I was thinking if it wouldn't be better to name it mobile-guides (or something similar) instead of mobile-docs? It might be confusing to have so many "docs" around. But I might be wrong, it's just an idea.

I'm assuming that the release tagging for <service>-apb repo is always the 'version number' we want to communicate to end users?

I'm not sure about the tagging but @David might know the answer?

There is tagging on (some?) apbs with a version to date.

e.g. 

https://github.com/aerogearcatalog/keycloak-apb/tree/0.0.6

But that may have been from the proof of concept phase.

I'm sure we can rely on some version tagging going forward though as we do a 'release' of 5.x (whatever that means)

--

David Martin

Red Hat Mobile

Twitter: @irldavem

IRC: @irldavem (#aerogear)

[Vojtech Sazel]

On Tue, Feb 13, 2018 at 11:45 AM, <cro...@redhat.com> wrote:

Hey guys,

Looking at the proposed layout, I am wondering where would be an appropriate place to store auto-generated docs, like javadoc etc. As it is not common practice to store these in the source repo. If we are following the below layout, where do you think would be the best place to keep the likes of Javadocs. 

As it's being probably generated by Jenkins/CircleCI. I propose that automatically generated docs should be part of the releases page, like as ZIP in here https://github.com/aerogear/mobile-cli/releases. 

But we need probably to view them online as well. I was thinking about having it in gh-pages. You guys probably have more experience with documenting open-source projects, I found only this on StackOverflow:

https://stackoverflow.com/questions/15347808/display-javadocs-on-github
 

https://github.com/aerogear:

* mobile-docs

* <sdk>/docs

* mobile-cli/docs

https://github.com/aerogearcatalog

* <service>-apb/docs

--
You received this message because you are subscribed to the Google Groups "Aerogear" group.
To unsubscribe from this group and stop receiving emails from it, send an email to aerogear+unsubscribe@googlegroups.com.
To post to this group, send email to aero...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/aerogear/e3ff3061-31b6-4618-a1f7-21e406c45b10%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

VOJTĚCH SÁZEL

SENIOR SOFTWARE ENGINEER, RED HAT MOBILE

Red Hat 

Remote Czech Republic

vsa...@redhat.com    IM: vsazel

[Paul Wright]

On 02/13/2018 07:16 PM, Vojtech Sazel wrote:

On Tue, Feb 13, 2018 at 11:45 AM, <cro...@redhat.com> wrote:

Hey guys,

Looking at the proposed layout, I am wondering where would be an appropriate place to store auto-generated docs, like javadoc etc. As it is not common practice to store these in the source repo. If we are following the below layout, where do you think would be the best place to keep the likes of Javadocs. 

As it's being probably generated by Jenkins/CircleCI. I propose that automatically generated docs should be part of the releases page, like as ZIP in here https://github.com/aerogear/mobile-cli/releases.

Interesting, I already build test 'docsets' using circleci [1], nice idea to 'release' them formally,

But we need probably to view them online as well. I was thinking about having it in gh-pages.

Agreed, gh-pages is way to go. IMO, the choices are to push html to:

* gh-pages branch of mobile-docs
* /docs directory of master on mobile-docs
* master branch of a dedicated mobile-docs-html repo

My preference is for last option (to minimize bloat/confusion). In theory, the only thing we ever want to do with the html is to push it, but we want to push it often and not worry about conflicts/source.

WDYT?

You guys probably have more experience with documenting open-source projects, I found only this on StackOverflow:

https://stackoverflow.com/questions/15347808/display-javadocs-on-github

thanks, good info there.

 

https://github.com/aerogear:

* mobile-docs

* <sdk>/docs

* mobile-cli/docs

https://github.com/aerogearcatalog

* <service>-apb/docs

--
You received this message because you are subscribed to the Google Groups "Aerogear" group.
To unsubscribe from this group and stop receiving emails from it, send an email to aerogear+unsubscribe@googlegroups.com.
To post to this group, send email to aero...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/aerogear/e3ff3061-31b6-4618-a1f7-21e406c45b10%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

VOJTĚCH SÁZEL

SENIOR SOFTWARE ENGINEER, RED HAT MOBILE

Red Hat 

Remote Czech Republic

vsa...@redhat.com    IM: vsazel

--
You received this message because you are subscribed to the Google Groups "Aerogear" group.

To unsubscribe from this group and stop receiving emails from it, send an email to aerogear+u...@googlegroups.com.

To post to this group, send email to aero...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/aerogear/CAGTW8rH5S%3DF2EN9wzu3fDps-pYufADV%3DLr9rE8a%2Bznuqc944PQ%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

[1] https://1-119057815-gh.circle-artifacts.com/0/home/circleci/docs/_preview/aerogear/latest/getting-started/mobile_terminology.html

-- 
Paul Wright
Mobile Docs (github: finp)

[Vojtech Sazel]

I agree it's better to have them in separate repo. Possibly this repo wouldn't be manually modified at all. Only links to the pages with Javadocs will be in mobile-docs repo.

To view this discussion on the web visit https://groups.google.com/d/msgid/aerogear/CAGTW8rH5S%3DF2EN9wzu3fDps-pYufADV%3DLr9rE8a%2Bznuqc944PQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[1] https://1-119057815-gh.circle-artifacts.com/0/home/circleci/docs/_preview/aerogear/latest/getting-started/mobile_terminology.html

-- 
Paul Wright
Mobile Docs (github: finp)

[Daniel Passos]

Hey

Talking specifically about the JavaDoc its auto-generated on every release and published in javadoc.io. Here is an example: http://www.javadoc.io/doc/org.jboss.aerogear/aerogear-android-pipe/4.0.0

--
You received this message because you are subscribed to the Google Groups "Aerogear" group.
To unsubscribe from this group and stop receiving emails from it, send an email to aerogear+unsubscribe@googlegroups.com.
To post to this group, send email to aero...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/aerogear/e3ff3061-31b6-4618-a1f7-21e406c45b10%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

-- Passos

[Wojciech Trocki]

For TypeScript (type-doc) people usually using github-pages npm module with github-pages hosting.
Same can be used to host IOS/Swift documentation (and JavaDoc if needed). 

To view this discussion on the web visit https://groups.google.com/d/msgid/aerogear/CADF%3Dh2sVQEUoTgC%3DO_rxz7Z1WuTwqa%2BsRcM1aeifycxoeb99WA%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--