Folder structure for documentation

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/user/admin_area/.
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/topics/ Indexes per topic (doc/topics/topic_name/index.md): all resources for that topic.

Work with directories and files

When working with directories and files:

  1. When you create a new directory, always start with an index.md file. Don’t use another filename and do not create README.md files.
  2. Do not use special characters and spaces, or capital letters in file names, directory names, branch names, and anything that generates a path.
  3. When creating or renaming a file or directory and it has more than one word in its name, use underscores (_) instead of spaces or dashes. For example, proper naming would be import_project/import_from_github.md. This applies to both image files and Markdown files.
  4. For image files, do not exceed 100KB.
  5. Do not upload video files to the product repositories. Link or embed videos instead.
  6. There are four main directories: user, administration, api, and development.
  7. The doc/user/ directory has five main subdirectories: project/, group/, profile/, dashboard/ and admin_area/.
    • 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/user/dashboard/ should contain all dashboard related documentation.
    • doc/user/admin_area/ should contain all administrator-related documentation describing what can be achieved by accessing the GitLab administrator interface (not to be confused with doc/administration where server access is required).
      • Every category under /admin/application_settings/ should have its own document located at doc/user/admin_area/settings/. For example, the Visibility and Access Controls category should have a document located at doc/user/admin_area/settings/visibility_and_access_controls.md.
  8. The doc/topics/ directory holds topic-related technical content. Create doc/topics/topic_name/subtopic_name/index.md when subtopics become necessary. General user and administrator documentation should be placed accordingly.
  9. The /university/ directory is deprecated and the majority of its documentation has been moved.

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.

Avoid duplication

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:

References across documents

  • Give each folder an 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.
  • To ensure discoverability, ensure each new or renamed doc is linked from its higher-level index page and other related pages.
  • When making reference to other GitLab products and features, link to their respective documentation, at least on first mention.
  • When making reference to third-party products or technologies, link out to their external sites, documentation, and resources.