doc_styleguide.md

Documentation styleguide

This styleguide recommends best practices to improve documentation and to keep it organized and easy to find.

Location and naming of documents

Note: These guidelines derive from the discussion taken place in issue #3349.

The documentation hierarchy can be vastly improved by providing a better layout and organization of directories.

Having a structured document layout, we will be able to have meaningful URLs like docs.gitlab.com/user/project/merge_requests.html. With this pattern, you can immediately tell that you are navigating a user related documentation and is about the project and its merge requests.

The table below shows what kind of documentation goes where.

Directory	What belongs here
doc/user/	User related documentation. Anything that can be done within the GitLab UI goes here including /admin.
doc/administration/	Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under doc/user/admin_area/.
doc/api/	API related documentation.
doc/development/	Documentation related to the development of GitLab. Any styleguides should go here.
doc/legal/	Legal documents about contributing to GitLab.
doc/install/	Probably the most visited directory, since installation.md is there. Ideally this should go under doc/administration/, but it's best to leave it as-is in order to avoid confusion (still debated though).
doc/update/	Same with doc/install/. Should be under administration/, but this is a well known location, better leave as-is, at least for now.

---

General rules:

1. The correct naming and location of a new document, is a combination of the relative URL of the document in question and the GitLab Map design that is used for UX purposes (source, image).
2. When creating a new document and it has more than one word in its name, make sure to use underscores instead of spaces or dashes (-). For example, a proper naming would be import_projects_from_github.md. The same rule applies to images.
3. There are four main directories, user, administration, api and development.
4. The doc/user/ directory has five main subdirectories: project/, group/, profile/, dashboard/ and admin_area/.
   1. doc/user/project/ should contain all project related documentation.
   2. doc/user/group/ should contain all group related documentation.
   3. doc/user/profile/ should contain all profile related documentation. Every page you would navigate under /profile should have its own document, i.e. account.md, applications.md, emails.md, etc.
   4. doc/user/dashboard/ should contain all dashboard related documentation.
   5. doc/user/admin_area/ should contain all admin related documentation describing what can be achieved by accessing GitLab's admin interface (not to be confused with doc/administration where server access is required).
      1. 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.

---

If you are unsure where a document should live, you can ping @axil in your merge request.

Text

• Split up long lines, this makes it much easier to review and edit. Only double line breaks are shown as a full line break in GitLab markdown. 80-100 characters is a good line length
• Make sure that the documentation is added in the correct directory and that there's a link to it somewhere useful
• Do not duplicate information
• Be brief and clear
• Unless there's a logical reason not to, add documents in alphabetical order
• Write in US English
• Use single spaces instead of double spaces

Formatting

• Use dashes (-) for unordered lists instead of asterisks (*)
• Use the number one (1) for ordered lists
• Use underscores (_) to mark a word or text in italics
• Use double asterisks (**) to mark a word or text in bold
• When using lists, prefer not to end each item with a period. You can use them if there are multiple sentences, just keep the last sentence without a period

Headings

• Add only one H1 title in each document, by adding # at the beginning of it (when using markdown). For subheadings, use ##, ### and so on
• Avoid putting numbers in headings. Numbers shift, hence documentation anchor links shift too, which eventually leads to dead links. If you think it is compelling to add numbers in headings, make sure to at least discuss it with someone in the Merge Request
• Avoid adding things that show ephemeral statuses. For example, if a feature is considered beta or experimental, put this info in a note, not in the heading.
• When introducing a new document, be careful for the headings to be grammatically and syntactically correct. It is advised to mention one or all of the following GitLab members for a review: @axil, @rspeicher, @marcia, @SeanPackham. This is to ensure that no document with wrong heading is going live without an audit, thus preventing dead links and redirection issues when corrected
• Leave exactly one newline after a heading

Links