Create docs for the docs project
Problem
Currently, we have only a single (large) README.md
file for all the documentation regarding the docs project: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/README.md
This creates trouble as we try to document all the docs project processes, code, changes, etc.
For example:
-
Due to a lack of a good place to put it, we have all the release process documentation in the technical writing team's handbook page: https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases. Almost every link in that section (and its subsections) link to this project. So all of it should live here instead.
-
A lot of the information in https://docs.gitlab.com/ee/development/documentation/site_architecture/index.html is specific to the docs project, not the
gitlab
project, and should be documented here.All the docs in that page (and related pages in
gitlab
) are saved in the/help
docs for every self managed instance, including silo'ed instances.
Multiple recent discussions made me realize we really need to have a better place for docs project documentation:
- The discussion in #1038 (comment 605415034). There is currently no good place for the docs Amy (correctly) recommends.
- Docs site release docs improvements. I started creating an MR for the tech writing team's handbook page to update the process, and it struck that I was doing it in the wrong place, especially when I have to combine it with a separate MR to update the processes/issue template here.
We really don't have a good system to answer these questions:
- "I am an onboarding TW, where do I go to learn everything the docs project does?"
- "We are changing how the docs site/project works, where do we document this change?"
Proposal
We should create a new /doc
directory in this project, and maintain all the documentation that is specific to the Docs project here.
This would be similar to the docs in the gdk
project, which also has a full set of docs in /doc
: https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/main/doc
Things to document here in /doc
:
- Nanoc details (currently in https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/README.md)
- Backend/frontend considerations that are specific to the docs project, for example:
- The "introduced in" text formatter
- Code block coloring
- Any details we want to document about the typescale/style
- Docker images
- Pipelines
- Various undocumented scripts and raketasks
- We have several access tokens in use, undocumented.
- Monthly chores task details
- Docs project release process (as mentioned above)
- etc.
One big advantage is it will be far easier to keep all the various docs up to date, because we can update docs and code in the same MRs. For example, these sections are updated completely independently of the changes in the docs site:
- https://docs.gitlab.com/ee/development/documentation/site_architecture/global_nav.html
- https://docs.gitlab.com/ee/development/documentation/site_architecture/index.html
If they were in gitlab-docs
, we would be able to update them at the same time as any changes, and keep everything in sync. It also means that people won't need to switch back and forth between multiple projects to accomplish one task.
Tracking this work will be easier as well, as we'll be able to use the documentation and ~docs::
labels too.