Docs Structure Discussion - One or Many Repos

The current plan for docs is that we will have:

One unified set of docs for all the components of ODK

I'm starting this thread to expand the discussion on this point, and give people an opportunity to weigh in on it.

In conversation with @yanokwa and Hélène Martin recently, we discussed the pros/cons of:

  • keeping all the docs as a single repository
  • breaking out the docs for each component (Collect, Aggregate, etc.) into a separate repo.

Choice 1: Keep everything together

Benefits

  • Simpler
  • Easier to triage incoming doc bugs and requests
  • Easier to navigate, especially if you're not sure which component is causing a problem
  • Many of the difficulties people have (and need docs for) involve integration problems

Problems with this approach

  • Difficult, or possibly impossible, to keep separate version-specific info on each component.

Choice 2: Individual Doc Repos for Each Component

Benefits

  • Each component is on a separate release cycle. By having separate docs repo, we could tie docs releases to product releases, ensuring that people on disparate versions would have access to the version-specific docs they need.

Problems

  • More complicated
  • We would probably still need a unifying "integration" documentation set
  • Triaging bugs — and having to move docs-related bugs from repo to repo — could get annoying and possibly hard to track.

Current Plan

Right now I am going to forge ahead with a single repo until we have most of the docs done. At that point, we can split them off if we decide we need to. In the meantime, this thread is open to discuss issues, problems, and solutions.

Discussion Questions

All relevant opinions are welcome, of course. I would find it helpful if you all could think about and discuss some of the following:

  • Have you had problems with existing documentation sources related to versioning?
  • How often do you have problems and aren't sure which component is the source of the problem?
  • If you have used or worked on other similar projects, what has been your experience with how these problems were handled?
  • Do you think multiple repos would discourage you from contributing to the documentation?
2 Likes

I think having an overall outline for the documentation would be a helpful item to guide this conversation.

How do the various parts of the docs (focused on different "levels" of users, e.g. person setting up servers, person authoring forms, person just managing survey implementation) get organized?

Also depending on the delivery method, the raw docs could be maintained in separate places but then presented in a combined format for the end-user (e.g. on part of the odk website)?

3 Likes

My personal experience is that a bit of time searching this forum leads to a wealth of information which addresses most questions which arise, but not always to established documentation. I like Dan's idea for an overall outline for documentation, which we can link to the repo. Would be nice to link responses to common questions directly to the noted documentation in the repo.

3 Likes

This is just a suggestion. Maybe there must be a different branch as long as the documentation is still under development?
Also, as I just started to contribute on the documentation, I personally believe that there must be a single repository altogether. At most if it's really necessary separate branches could be created in the same repo.

2 Likes

Thanks for your comments.
We've all pretty much settled on the single repo approach.
As you've realized too, the complication of multiple repos for tightly-coupled products doesn't make a lot of sense.

Branches are for in progress work.