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?