There are some fantastic efforts to generate and update useful developer-facing documentation so we really need to have a clear place for it to go. For example:
- @michal_dudzinski has started writing up some information about the way relevants, calculates and constraints are evaluated in JavaRosa - https://github.com/opendatakit/docs/pull/413. This is sensitive code that is at the core of how Collect works. It would be helpful for more developers to be aware of it and understand it at least at a high level.
- @jknightco has started introducing some modern Android architecture to Collect and has written up some documentation for understanding that architecture and the libraries involved https://github.com/opendatakit/collect/pull/1678#issuecomment-349303609
- @Akshay_Patel has started exploring other areas of the Collect code base that could use documentation to help new developers get started What would you like to see in Collect developer documentation?
My current preference would be for as much documentation as possible to reside at docs.opendatakit.org including documentation for developers of ODK tools and ODK-compatible tools. An example of that mix is the curl book. See https://ec.haxx.se/sourcecode.html for developer docs and notice that user docs are also there. This is my preference because:
- Wikis in general don't make it easy to have a review process. I think we'd want all docs to be reviewed by at least one person other than the author.
- When I'm looking for a piece of information as a developer, it's often in the user docs. Concentrating all docs in one place means I don't have to search multiple places.
- Although I agree with @downey in Future of new ODK web site? - #26 by downey that site search will be very helpful, if I'm already on the docs site it's nice to be able to search there and get meaningful results.
- A wiki would either require a separate login or if using GitHub, granting commit privileges to the corresponding repo.
I think that adding a Development section to docs with subsections by tool could work well. Ideally we could also have a standard banner at the top that says something like "This document is meant for developers, please see < link > for user documentation" in case users end up there.
What do others think?