How to organize everything

[yucombinator]

Not sure what is the best way to organize information:

We can either do:

• List all manufacturers and then show issues per OEM
• List different parts of the SDK and link to another page that lists device specific hacks.

[anas-ambri]

Thanks @icechen1 for taking the initiative to start this!

The problem with organization is the following:

• OEM issues affect development during different stages. For example, the camera orientation flip will happen during development or testing, while the MenuBuilder crash won't appear until after release.
• You want the list of issues to be easily searchable. For example, when I type the stacktrace of my crash, the info should be in the top results.

Personally, I would like to see this made into two parts. First, a checklist-like document, specific to each device, that lists the issues that cannot be caught during development, to look out for before releasing. This could be modelled as an aggregate of Stackoverflow questions. Involvement of the community would be very important (through pull requests?) because only people with specific devices could actually report fixes.

A second part, which I think would be much more useful, is a list of quirks that are API-specific. Something like canIUse. You type in the API, and it lists all the warnings to keep in mind.

[yucombinator]

:+1: on having a navigable/searchable site like canIUse. Looking at the source everything seems to be stored in giant json files, which makes contributing a bit hard.

Alternatively we can also set up a wiki-type engine like mediaWiki which makes things searchable and also easy to edit, but I haven't had too much experience setting one up, so I'm not entirely sure if it could do everything we want.

[skrzyneckik]

What's about structure similar to Official Android Documentation? Make thick copy of all of methods aggregated in classes without description of those methods. Than every method, which is bugged on some devices / works different than expected / is affected by bugs would be annotated with all of reported bugs. This project would be kind of documentation of bugs coverage in Android API.

[anas-ambri]

I like @szpecku's idea very much. We could remove a lot of clutter from the Android docs, and then find some way to merge all the annotated info into the static pages.

Any idea of what format to use for these annotations? As @icechen1 said, canIUse seem to be using JSON.