Most of the high-level items on the rapidly growing https://docs.opendatakit.org site are user-facing, but there are developer docs (e.g. OpenRosa, JavaRosa) also there.
I think this can be a bit confusing for users because you are looking at Aggregate, Briefcase, Collect, Form Building, then all of a sudden, OpenRosa!
One option is to move more developer facing docs under a Development section (or something similar)? I haven't thought this all the way through but wanted to start a discussion!
Given the diverse (and in some case ad hoc) nature of "ODK developer documentation", might it be worth considering pulling relevant info out of all the various sources its currently squirreled away in - JavaRosa, OpenRosa, XLSForm, GitHub, opendatakit.org - under a wiki?
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.
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.
ONE PLACE for dos, period. This is very attractive.
Editorial oversight on dev docs, making them (one hopes) higher quality than they otherwise would be.
An tendency/motivation towards completeness and quality -- since docs are being published on an attractive (i hope) public site with traffic (not just in a repo's readme)
Ease of cross referencing
A single build/deploy pipeline for all docs -- no docs left behind
well-established docs contribution process might make it easier to get more contributions for dev docs than otherwise, and make it easier to (for example) improve dev docs through programs like outreachy and GSOC
implementers and developers are overlapping sets; also third-party devs and core devs are overlapping sets; and their needs/concerns are overlapping -- so a separation of their doc sets is a little artificial
Cons(iderations):
it is unlikely that dev docs would be very complete soon. so we would likely be publishing incomplete docs to our live site for some time. We already do this a little, but this would increase that.
some devs (in my experience) don't appreciate the structure of Sphinx or the syntax of RST, leading to a whole lot of "can't we just use markdown on gh ages or a wiki" complaining.
this presents a minor organizational challenge, as "dev docs" is actually several sets of docs for different projects, each with potentially its own needs, contributor guidelines, etc.
More can probably be added to both lists.
On a personal note:
I find working on dev docs to be more fun than user docs. Also, I like my job and don't want to run out of things to do. For those two reasons, I would -- for my own benefit -- advocate for folding dev docs into docs.opendatakit.org. Those aren't good enough reasons to make a community-impacting decision, but... it thought I'd mention them, and say i am in full support of it, if it seems to most folks that it is the best way to go.
I should also mention, there are good tools for extracting javadoc (and similar) documentation out of code and inserting it into a sphinx build. That is not the only type of dwv doc needed, but it can really help with wayfinding in an unfamiliar codebase.
Another option I like is Python's https://devguide.python.org/ which is separate from https://docs.python.org but uses the same Sphinx tooling. That could make us feel more free to expand the scope of what a dev doc is, centralize contribution guides and so on. In general, I like their content very much.
The Technical Steering Committee will come into existence on Jan 1. This will have some impact on both this conversation and the website one as some information needs will shift. The TSC will start generating content that will need a home including meeting minutes, roadmaps, etc. That content could potentially fit alongside dev docs. I imagine the TSC will have conversations about the most appropriate place for those and will be able to comment here as well.
Centralized dev docs, but still separate from user docs, might be a good thing. OR we could start with the together and separate them if we realize:
there isn't actually much interlinking need
there's too much dev stuff to organize well under a single "For Developers" TOC
FWIW - I think the potential for overlapping/duplicate information is the most compelling reason to keep things together. So, it's worth thinking about whether that would be the case, or if there is(are) really (a) bright line(s) between information needed by users, implementers, core developers, and third party developers.
I think that we will want to create "content spaces" that are unified under a broader look at where the ODK project content should go as content is migrated to new homes as part of the project change with the new TSC and new website.
I am personally a fan of having a second URL for developer docs like dev-guide.opendatakit.org as the user audience is often quite different than the contributor audience.