How to manage development docs for "other" projects
Following the discussion in this thread: !2867 (comment 1007324003), and specifically this comment: !2867 (comment 1015170046), I think we need to discuss how we manage the development docs for GitLab-related products and projects.
In gitlab-pages!718 (comment 919809402), there was some good discussion about the dev docs for GitLab Pages, and the decision was to copy the docs into the gitlab
repo. The code itself is not in that repo though, so this was done to make the docs more easily findable, and perhaps increase contributions to that project as a result.
But this now suggests that we have at least 3 different ways of handling docs like this (I suppose it applies to all docs in these repos, not just dev docs):
- Completely stand-alone, code and docs all together in the project, disconnected from the
gitlab-docs
project. Advantage: Everything stays in sync more easily. For example: - Fully in the main docs, pulled away from the code. Advantage: More discoverability as it will come up in docs site searches. For example:
- GitLab Pages: https://docs.gitlab.com/ee/development/pages/
- Hybrid solution, where the docs stay with the code, but are pulled into the docs site at build time. Advantage: Best of both worlds, but needs the most amount of work and maintenance. For example:
- GitLab Operator: https://docs.gitlab.com/operator/developer/guide.html (docs site), https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/master/doc/developer/guide.md (file location).
Should we pick a standard for this kind of documentation? Or should we perhaps offer some guidelines for when to choose each option?