doc/development/documentation/site_architecture/folder_structure.md
The documentation is separated by top-level audience folders user,
administration,
and development
(contributing) folders.
Beyond that, we primarily follow the structure of the GitLab user interface or API.
Our goal is to have a clear hierarchical structure with meaningful URLs like
docs.gitlab.com/user/project/merge_requests/. With this pattern, you can
immediately tell that you are navigating to user-related documentation about
project features; specifically about merge requests. Our site's paths match
those of our repository, so the clear structure also makes documentation easier
to update.
Put files for a specific product area into the related folder:
| Directory | Contents |
|---|---|
doc/user/ | Documentation for users. Anything that can be done in the GitLab user interface goes here, including usage of the /admin interface. |
doc/administration/ | Documentation that requires the user to have access to the server where GitLab is installed. Administrator settings in the GitLab user interface are under doc/administration/. |
doc/api/ | Documentation for the API. |
doc/development/ | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. |
doc/legal/ | Legal documents about contributing to GitLab. |
doc/install/ | Instructions for installing GitLab. |
doc/update/ | Instructions for updating GitLab. |
doc/tutorials/ | Tutorials for how to use GitLab. |
The following are legacy or deprecated folders. Do not add new content to these folders:
/gitlab-basics//topics//university/When working with directories and files:
_index.md file.
Don't use another filename and do not create README.md files.-) instead of spaces or underscores.
For example, proper naming would be import-project/import-from-github.md. This applies
to both image files and Markdown files.doc/user/ directory:
doc/user/project/ should contain all project related documentation.doc/user/group/ should contain all group related documentation.doc/user/profile/ should contain all profile related documentation.
Every page you would navigate under /profile should have its own document,
for example, account.md, applications.md, or emails.md.doc/administration/ directory: all administrator-related
documentation for administrators, including admin tasks done in both
the UI and on the backend servers.If you're unsure where to place a document or a content addition, this shouldn't stop you from authoring and contributing. Use your best judgment, and then ask the reviewer of your MR to confirm your decision. You can also ask a technical writer at any stage in the process. The technical writing team reviews all documentation changes, regardless, and can move content if there is a better place for it.
When possible, do not include the same information in multiple places. Link to a single source of truth instead.
For example, if you have code in a repository other than the primary repositories, and documentation in the same repository, you can keep the documentation in that repository.
Then you can either:
_index.md page that introduces the topic, and both introduces
and links to the child pages, including to the index pages of
any next-level sub-paths.