Documentation guidelines
This is an issue for extending doc_styleguide.md.
These are things I come across while reviewing/enhancing documentation.
- Headings (aka broken links)
-
Avoid putting numbers in Markdown headings (gitlab-foss#3794 (closed)) -
When introducing a new doc, be careful for the headings to be grammatically and syntactically correct. It is advised to mention one or all of the following for a review: @axil
,@JobV
,@rspeicher
,@ashleys
,@dblessing
,@nearlythere
. This is to ensure that no docs with wrong heading is going live without an audit.
-
- New features
-
Every piece of documentation that comes with a new feature should declare the GitLab version that feature got introduced. We should agree upon a common text that will be the same for all mentions, eg This feature got introduced in GitLab 8.2. -
?If possible every feature should have a link to the MR that introduced it (this might be tricky since we iterate over things and tend to change down the road). -
Do not add headings for Parameters
,Example of request
andExample of response
, add only for the main calls. Always imagine that the headings end up being referenced in doc.gitlab.com. How would you know what is referenced if your URL isapi/build_variables.md#parameters
? If you have multiple times the same heading you would not know where to go.not add headings forParameters
,Example of request
andExample of response
, add only for the main calls. Always imagine that the headings end up being referenced in doc.gitlab.com. How would you know what is referenced if your URL isapi/build_variables.md#parameters
? If you have multiple times the same heading you would not know where to go.
-
- Images
-
If there are consecutive images with little text between them, always add ---
between the image and the text to create a horizontal line for better clarity. -
If a heading is placed right after an image, always add ---
between the image and the heading. -
Place images in a separate directory named img
and always prepend their names with the document that they will be included in. For example, if there is a document calledtwitter.md
, then a possible image could beimg/twitter_login_screen.png
. -
Consider using PNG images and not JPEG.
-
- API
-
If pagination is used, add the following text between the H1 and the first H2 (provided the document is in doc/api/
):[Pagination](README.md#pagination) is used.
-
- Code blocks
-
Do not use $
or#
in the beginning of commands to denote non-privileged/root commands respectively. All commands are implied to run by a non-privileged user unless stated otherwise.
-