Decide the final location for Javadoc and examples

[cammace]

Releasing mapbox-java soon, we need to figure out the best place for the overview, examples, and javadoc. Pros and cons of the two options:

Incorporate it within mapbox.com/android-sdk
Pros:

• Better visibility to those who are already using Android SDK
• Easier to maintain

Cons:

• API tab immediately takes you to Android SDK Javadoc, would need option to pick which javadoc to view
• More clutter on each page
• Overview page would need separate page for each SDK

Make separate mapbox.com/mapbox-java page
Pros:

• API tab can take you directly to Mapbox-java javadoc
• Less cutter overall

Cons:

• Less visibility due to it being on separate page
• Harder to maintain

Thoughts? @danswick @lyzidiamond @tmcw @zugaldia @bleege @tobrun

[zugaldia]

cc: @1ec5 @friedbunny as they'll have to face eventually the same decision for iOS and they might have some insights on how to better handle this.

[bleege]

My initial reaction is that I really want to have this on /android-sdk but the more I think about the logistics I think it makes more sense to have it on it's own /android-services. Mapbox Android Services is technically a standalone product that one could use with other map tech (but why?) and it makes more sense to give it it's own dedicated space to have setup, examples, and API information. We can definitely cross link each of them, as well as incorporate Geocoding and Directions examples in the /android-sdk section.

[1ec5]

At this point, I expect that for the iOS libraries, the "truth" will live in documentation comments (since that's the only thing Xcode's Quick Help feature looks at), then we'll use SourceKitten (part of jazzy) to extract an AST for api-documentation's use. We can also generate the usual Apple-style HTML documentation via jazzy and publish it somewhere.

[1ec5]

Wherever the iOS library's repo ends up, I think we'd want to publish the documentation in the mb-pages branch or in a docs/ directory in master, just as GL JS does.

[zugaldia]

I like the approach from @1ec5 to mimic the GL JS. How would this work for the time being?

• Javadocs in the mb-pages of this repo.
• Install/overview instructions in the README.md in this repo.
• Samples as subsection in the left column in https://www.mapbox.com/android-sdk/examples/.

Thoughts?

[cammace]

This is probably the best option for keeping things organized as well as visible to developers. I'll begin work on adding an overview style to the README.md file and create a few examples within the android-sdk docs.

[danswick]

I'm 👎 on keeping mapbox-java docs separate from android-sdk docs, or would at least like to see some thoughtful integration between the two. Organizing mapbox-java docs in the repo's mb-pages branch is convenient from a development standpoint, but I'm wary about adding another layer of complexity to our already fragmented documentation landscape. At the very least, I would prefer to see android-java examples stay on the android-sdk page and would like to add a section to the overview explaining what android-java is and how it works in concert with the SDK.

As @bleege points out, android-java can be used separately from our SDK, but 1) why? and 2) we shouldn't cater our documentation to this audience.

[danswick]

Per chat with @cammace, I'm thinking the best course of action is to go ahead with a separate javadoc via an mb-pages branch and focus on tight overview narrative and examples, to be housed at mapbox.com/android-sdk for the time being. This approach gives us the leeway to launch quickly, evaluate the response from our users, and reshuffle the docs later as necessary.

[bleege]

I'm thinking the best course of action is to go ahead with a separate javadoc via an mb-pages branch and focus on tight overview narrative and examples, to be housed at mapbox.com/android-sdk for the time being.

👍

[cammace]

I've moved discussion and a rough draft on this topic within mapbox/android-sdk#95

[zugaldia]

Closing this one so that the convo can continue there.