Where should we put developer docs?

Development
1

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!

1 Like
2

And there's a JavaRosa page under Form Building, but OpenRosa is a bunch of docs that need an umbrella.

One question that would be helpful to answer:

What other developer-facing docs are we likely to create?

3

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?

4

  • OpenRosa API specs have already been moved into the docs, and the old OpenRosa pages will be deprecated.

  • XLSForm is not maintained by ODK.

  • We are already in the process of migrating info from opendatakit.org to docs.opendatakit.org and deprecating the old pages

  • There is already a developer wiki.

    • The current developer wiki is explicitly for ODK developers.
    • Currently, docs for ODK developers are out of scope for docs.opendatakit.org.
    • The subject of this thread is docs for third party developers who have a need to interface with ODK components
1 Like
5

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:

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?

6

I could go either way with dev docs in docs.opendatakit.org.

Pros:

  • 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.

7

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.

8

This is very true.

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.

1 Like
9

+1 to doing whatever Python is doing.

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.

1 Like
10

Not only is the new Technical Steering Committee starting up, we also have website redesign going on Future of new ODK web site?.

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.

11

According to me user docs and developer docs should be separate as the target readers are different.

2 Likes