Documentation Style Guide

This document defines the standards for Roivant IT documentation, including grammar, formatting, word use, and more.

In addition to this page, the following resources can help you craft and contribute to documentation:

• Doc style and consistency testing
• UI text guidelines
• Roivant IT Handbook style guidelines
• Microsoft Style Guide
• Google Developer Documentation Style Guide

The documentation includes all media types

Include any media types/sources if the content is relevant to readers. You can freely embed or link presentations, diagrams, O365 docs and videos. No matter who it was originally composed for, if it is helpful to any of our audiences, we can include it.

• If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone.
• Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source.

Link instead of repeating text

Rather than repeating information from another topic, link to the single source of truth and explain why it is important.

Docs-first methodology

We employ a documentation-first methodology. This method ensures the documentation remains a complete and trusted resource, and makes communicating inside Roivant IT more efficient.

• If the answer to a question exists in documentation, share the link to the documentation instead of rephrasing the information.
• When you encounter new information not available in current documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request (MR) to add this information to the documentation. You can then share the MR to communicate this information.

New information that would be useful toward future functions or troubleshooting should not be written directly in a forum or other messaging system, but added to a documentation MR and then referenced, as described above.

The more we reflexively add information to the documentation, the more the documentation helps others efficiently accomplish tasks and solve problems.

Markdown

In Roivant IT, documentation is written using Markdown.

HTML in Markdown

Hard-coded HTML is valid, although it’s discouraged from being used. HTML is permitted if:

• There’s no equivalent markup in Markdown.
• Advanced tables are necessary.
• Special styling is required.
• Reviewed and approved by a technical writer.

Markdown Rules

Roivant IT ensures that the Markdown used across all documentation is consistent, as well as easy to review and maintain, by testing documentation changes with markdownlint. This lint test fails when any document has an issue with Markdown formatting that may cause the page to render incorrectly.

Avoid duplication

Do not include the same information in multiple places. Link to a single source of truth instead.

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 Roivant IT teams, products or services, 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.

Structure in documents

• Structure content in alphabetical order in tables, lists, and so on, unless there’s a logical reason not to (for example, when mirroring the user interface or an otherwise ordered sequence).

Language

Roivant IT documentation should be clear and easy to understand.

• Avoid unnecessary words.
• Be clear, concise, and stick to the goal of the topic.
• Write in US English with US grammar.

Capitalization

Headings

Use sentence case. For example:

• # Use variables to configure pipelines
• ## Use the To-Do List

Contractions

Contractions are encouraged, and can create a friendly and informal tone, especially in tutorials and instructional documentation.

Some contractions, however, should be avoided:

• Do not use contractions with a proper noun and a verb. For example:

  Do	Don’t
  Canada is establishing X.	Canada’s establishing X.

• Do not use contractions when you need to emphasize a negative. For example:

  Do	Don’t
  Do not install X with Y.	Don’t install X with Y.

• Do not use contractions in reference documentation. For example:

  Do	Don’t
  Do not set a limit greater than 1000.	Don’t set a limit greater than 1000.
  For parameter1, the default is 10.	For parameter1, the default’s 10.

• Avoid contractions in error messages. Examples:

  Do	Don’t
  Requests to localhost are not allowed.	Requests to localhost aren’t allowed.
  Specified URL cannot be used.	Specified URL can’t be used.

Text

• Write in Markdown.

• Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text.

• Insert an empty line for new paragraphs.

• Insert an empty line between different markups (for example, after every paragraph, header, list, and so on). Example:

  ## Header
  
  Paragraph.
  
  - List item 1
  - List item 2
  

Emphasis

• Use double asterisks (**) to mark a word or text in bold (**bold**).
• Use underscore (_) for text in italics (_italic_).
• Use greater than (>) for blockquotes.

Punctuation

Follow these guidelines for punctuation:

Placeholder text

You might want to provide a command or configuration that uses specific values.

In these cases, use < and > to call out where a reader must replace text with their own value.

For example:

cp <your_source_directory> <your_destination_directory>

Keyboard commands

Use the HTML <kbd> tag when referring to keystroke presses. For example:

To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>.

When the docs are generated, the output is:

To stop the command, press Control+C.

Spaces between words

Use only standard spaces between words. The search engine for the documentation website doesn’t split words separated with non-breaking spaces when indexing, and fails to create expected individual search terms. Tests that search for certain words separated by regular spaces can’t find words separated by non-breaking spaces.

Lists

• Always start list items with a capital letter, unless they’re parameters or commands that are in backticks, or similar.
• Always leave a blank line before and after a list.
• Begin a line with spaces (not tabs) to denote a nested sub-item.

Ordered vs. unordered lists

Only use ordered lists when their items describe a sequence of steps to follow.

Do:

These are the steps to do something:

1. First, do the first step.
1. Then, do the next step.
1. Finally, do the last step.

Don’t:

This is a list of available features:

1. Feature 1
1. Feature 2
1. Feature 3

Markup

• Use dashes (-) for unordered lists instead of asterisks (*).
• Prefix 1. to every item in an ordered list. When rendered, the list items display with sequential numbering.

Punctuation

• Don’t add commas (,) or semicolons (;) to the ends of list items.

• Only add periods to the end of a list item if the item consists of a complete sentence (with a subject and a verb).

• Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period.

• Separate list items from explanatory text with a colon (:). For example:

  The list is as follows:
  
  - First item: this explains the first item.
  - Second item: this explains the second item.
  

Examples:

Do:

• First list item
• Second list item
• Third list item

Don’t:

• First list item
• Second list item
• Third list item.

Do:

• Let’s say this is a complete sentence.
• Let’s say this is also a complete sentence.
• Not a complete sentence.

Don’t (vary use of periods; majority rules):

• Let’s say this is a complete sentence.
• Let’s say this is also a complete sentence.
• Not a complete sentence

Nesting inside a list item

It’s possible to nest items under a list item, so that they render with the same indentation as the list item. This can be done with:

• Code blocks
• Blockquotes
• Alert boxes
• Images

Items nested in lists should always align with the first character of the list item. In unordered lists (using -), this means two spaces for each level of indentation:

- Unordered list item 1

  A line nested using 2 spaces to align with the `U` above.

- Unordered list item 2

  > A quote block that will nest
  > inside list item 2.

- Unordered list item 3

  ```plaintext
  a code block that nests inside list item 3
  ```

- Unordered list item 4

  ![an image that will nest inside list item 4](image.png)

For ordered lists, use three spaces for each level of indentation:

1. Ordered list item 1

   A line nested using 3 spaces to align with the `O` above.

1. Ordered list item 2

   > A quote block that will nest
   > inside list item 2.

1. Ordered list item 3

   ```plaintext
   a code block that nests inside list item 3
   ```

1. Ordered list item 4

   ![an image that will nest inside list item 4](image.png)

You can nest full lists inside other lists using the same rules as above. If you want to mix types, that’s also possible, if you don’t mix items at the same level:

1. Ordered list item one.
1. Ordered list item two.
   - Nested unordered list item one.
   - Nested unordered list item two.
1. Ordered list item three.

- Unordered list item one.
- Unordered list item two.
  1. Nested ordered list item one.
  1. Nested ordered list item two.
- Unordered list item three.

Tables

Tables should be used to describe complex information in a straightforward manner. Note that in many cases, an unordered list is sufficient to describe a list of items with a single, simple description per item. But, if you have data that’s best described by a matrix, tables are the best choice.

Creation guidelines

To keep tables accessible and scannable, tables should not have any empty cells. If there is no otherwise meaningful value for a cell, consider entering N/A (for ’not applicable’) or none.

To help tables be easier to maintain, consider adding additional spaces to the column widths to make them consistent. For example:

| App name | Description          | Requirements   |
|:---------|:---------------------|:---------------|
| App 1    | Description text 1.  | Requirements 1 |
| App 2    | Description text 2.  | None           |

Consider installing a plugin or extension in your editor for formatting tables:

• Markdown Table Prettifier for Visual Studio Code
• Markdown Table Formatter for Sublime Text
• Markdown Table Formatter for Atom

Feature tables

When creating tables of lists of features (such the features available to each role on the Permissions page), use these phrases:

Footnotes

To indicate a footnote, use the HTML tag <sup> with a number. Put the tag at the end of the sentence or term.

For the footnotes below the table, use a bold number followed by a sentence.

For example:

| App name | Description                      |
|:---------|:---------------------------------|
| App A    | Description text. <sup>1</sup>   |
| App B    | Description text. <sup>2</sup>   |

1. This is the footnote.
1. This is the other footnote.

This text renders this output:

1. This is the footnote.
2. This is the other footnote.

Quotes

Valid for Markdown content only, not for front matter entries:

• Standard quotes: double quotes ("). Example: “This is wrapped in double quotes”.
• Quote inside a quote: double quotes (") wrap single quotes ('). Example: “This sentence ‘quotes’ something in a quote”.

Headings

• Add only one H1 in each document, by adding # at the beginning of it (when using Markdown). The h1 becomes the document <title>.
• Start with an h2 (##), and respect the order h2 > h3 > h4 > h5 > h6. Never skip the hierarchy level, such as h2 > h4
• 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.
• When possible, avoid including words that might change in the future. Changing a heading changes its anchor URL, which affects other linked pages.
• Leave exactly one blank line before and after a heading.
• Do not use links in headings.
• Our documentation site search engine prioritizes words used in headings and subheadings. Make your subheading titles clear, descriptive, and complete to help users find the right example, as shown in the section on heading titles.
• See Capitalization for guidelines on capitalizing headings.

Heading titles

Keep heading titles clear and direct. Make every word count. To accommodate search engine optimization (SEO), use the imperative, where possible.

For guidelines on capitalizing headings, see the section on capitalization.

NOTE: If you change an existing title, be careful. In-page anchor links, and links from external sites can break.

Anchor links

Headings generate anchor links when rendered. ## This is an example generates the anchor #this-is-an-example.

Important:

• Avoid crosslinking documentation to headings unless you need to link to a specific section of the document. This avoids breaking anchors in the future in case the heading is changed.
• If possible, avoid changing headings, because they’re not only linked internally.
• Do not link to h1 headings.

Links

We include guidance for links in these categories:

• How to set up anchor links for headings.
• How to set up criteria for configuring a link.
• How to set up links to external documentation for authoritative sources.
• When to use links requiring permissions.
• How to set up a link to a video.
• How to link to specific lines of code

Basic link criteria

• Use inline link Markdown markup [Text](https://example.com). It’s easier to read, review, and maintain. Do not use [Text][identifier] reference-style links.

• Use meaningful anchor texts. For example, instead of writing something like Read more about Roivant Miro Boards [here](LINK), write Read more about [Roivant Miro Boards](LINK).

Links to external documentation

When describing interactions with external software, it’s often helpful to include links to external documentation. When possible, make sure that you’re linking to an authoritative source. For example, if you’re describing a feature in Microsoft’s Active Directory, include a link to official Microsoft documentation.

Authoritative sources

When citing external information, use sources that are written by the people who created the item or product in question. These sources are the most likely to be accurate and remain up to date.

Examples of authoritative sources include:

• Specifications, such as a Request for Comments document from the Internet Engineering Task Force.
• Official documentation for a product. For example, if you’re setting up an interface with the Google OAuth 2 authorization server, include a link to Google’s documentation.
• Official documentation for a project. For example, if you’re citing NodeJS functionality, refer directly to NodeJS documentation.
• Books from an authoritative publisher.

Examples of sources to avoid include:

• Personal blog posts.
• Wikipedia.
• Non-trustworthy articles.
• Discussions on forums such as Stack Overflow.
• Documentation from a company that describes another company’s product.

While many of these sources to avoid can help you learn skills and or features, they can become obsolete quickly. Nobody is obliged to maintain any of these sites. Therefore, we should avoid using them as reference literature.

NOTE: Non-authoritative sources are acceptable only if there is no equivalent authoritative source. Even then, focus on non-authoritative sources that are extensively cited or peer-reviewed.

Links requiring permissions

Don’t link directly to:

• Confidential issues.
• Project data or information that requires special permissions to view.

These fail for:

• Those without sufficient permissions.
• Automated link checkers.

Instead:

• To reduce confusion, mention in the text that the information is either:
  • Contained in a confidential issue.
  • Requires special permission to a project to view.
• Provide a link in back ticks (`) so that those with access to the issue can navigate to it.

Example:

For more information, see the [confidential issue](../../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/<issue_number>`.

Link to specific lines of code

When linking to specific lines in a file, link to a commit instead of to the branch. Lines of code change over time. Linking to a line by using the commit link ensures the user lands on the line you’re referring to. The Permalink button, displayed when viewing a file in a project, provides a link to the most recent commit of that file.

• Do: [link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)
• Don’t: [link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).

If that linked expression has changed line numbers due to additional commits, you can still search the file for that query. In this case, update the document to ensure it links to the most recent version of the file.

Navigation

When documenting navigation through the user interface, use these terms and styles.

What to call the menus

Use these terms when referring to the main GitLab user interface elements:

• Top bar: This is the top bar that spans the width of the user interface. It includes the menu, the GitLab logo, search field, counters, and the user’s avatar.
• Left sidebar: This is the navigation sidebar on the left of the user interface, specific to the project or group.
• Right sidebar: This is the navigation sidebar on the right of the user interface, specific to the open issue, merge request, or epic.

How to document the menus

To be consistent, use this format when you write about UI navigation.

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Settings > CI/CD.
3. Expand General pipelines.

Another example:

1. On the top bar, select Menu > Groups and find your group.
2. On the left sidebar, select Settings > CI/CD.
3. Expand General pipelines.

An Admin Area example:

1. On the top bar, select **Menu >** **{admin}** **Admin**.

This text renders this output:

1. On the top bar, select Menu > {admin} Admin.

Images

Images, including screenshots, can help a reader better understand a concept. However, they can be hard to maintain, and should be used sparingly.

Before including an image in the documentation, ensure it provides value to the reader.

Capture the image

Use images to help the reader understand where they are in a process, or how they need to interact with the application.

When you take screenshots:

• Capture the most relevant area of the page. Don’t include unnecessary white space or areas of the page that don’t help illustrate the point. The left sidebar of the GitLab user interface can change, so don’t include the sidebar if it’s not necessary.
• Keep it small. If you don’t need to show the full width of the screen, don’t. A value of 1000 pixels is a good maximum width for your screenshot image.
• Be consistent. Coordinate screenshots with the other screenshots already on a documentation page. For example, if other screenshots include the left sidebar, include the sidebar in all screenshots.

Save the image

• Save the image with a lowercase filename that’s descriptive of the feature or concept in the image. If the image is of the GitLab interface, append the GitLab version to the filename, based on this format: image_name_vX_Y.png. For example, for a screenshot taken from the pipelines page of GitLab 11.1, a valid name is pipelines_v11_1.png. If you’re adding an illustration that doesn’t include parts of the user interface, add the release number corresponding to the release the image was added to; for an MR added to 11.1’s milestone, a valid name for an illustration is devops_diagram_v11_1.png.
• Place images in a separate directory named img/ in the same directory where the .md document that you’re working on is located.
• Consider using PNG images instead of JPEG.
• Compress all PNG images.
• Compress GIFs with https://ezgif.com/optimize or similar tool.
• Images should be used (only when necessary) to illustrate the description of a process, not to replace it.
• Max image size: 100KB (GIFs included).
• See also how to link and embed videos to illustrate the documentation.

Add the image link to content

The Markdown code for including an image in a document is: ![Image description which will be the alt tag](img/document_image_title_vX_Y.png)

The image description is the alt text for the rendered image on the documentation site. For accessibility and SEO, use descriptions that:

• Are accurate, succinct, and unique.
• Don’t use image of or graphic of to describe the image.

Compress images

You should always compress any new images you add to the documentation. One known tool is pngquant, which is cross-platform and open source. Install it by visiting the official website and following the instructions for your OS.

GitLab has a Rake task that you can use to automate the process. In the root directory of your local copy of https://gitlab.com/gitlab-org/gitlab, run in a terminal:

• Before compressing, if you want, check that all documentation PNG images have been compressed:

  bundle exec rake pngquant:lint
  

• Compress all documentation PNG images using pngquant:

  bundle exec rake pngquant:compress
  

The only caveat is that the task runs on all images under doc/, not only the ones you might have included in a merge request. In that case, you can run the compress task and only commit the images that are relevant to your merge request.

Videos

Adding GitLab YouTube video tutorials to the documentation is highly encouraged, unless the video is outdated. Videos should not replace documentation, but complement or illustrate it. If content in a video is fundamental to a feature and its key use cases, but isn’t adequately covered in the documentation, you should:

• Add this detail to the documentation text.
• Create an issue to review the video and update the page.

Do not upload videos to the product repositories. Link or embed them instead.

Link to video

To link out to a video, include a YouTube icon so that readers can scan the page for videos before reading:

<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Video Title](link-to-video).

You can link any up-to-date video that’s useful to the GitLab user.

Embed videos

Introduced in GitLab 12.1.

The GitLab documentation site supports embedded videos.

You can embed videos from the official YouTube account for GitLab only. For videos from other sources, link them instead.

In most cases, link to a video, because embedded videos take up a lot of space on the page and can be distracting to readers.

To embed a video:

1. Copy the code from this procedure and paste it into your Markdown file. Leave a blank line above and below it. Do not edit the code (don’t remove or add any spaces).
2. In YouTube, visit the video URL you want to display. Copy the regular URL from your browser (https://www.youtube.com/watch?v=VIDEO-ID) and replace the video title and link in the line under <div class="video-fallback">.
3. In YouTube, select Share, and then select Embed.
4. Copy the <iframe> source (src) URL only (https://www.youtube.com/embed/VIDEO-ID), and paste it, replacing the content of the src field in the iframe tag.

leave a blank line here
<div class="video-fallback">
  See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>.
</div>
<figure class="video-container">
  <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
leave a blank line here

This is how it renders on the GitLab documentation site:

Notes:

• The figure tag is required for semantic SEO and the video_container class is necessary to make sure the video is responsive and displays on different mobile devices.
• The <div class="video-fallback"> is a fallback necessary for /help, because the GitLab Markdown processor doesn’t support iframes. It’s hidden on the documentation site, but is displayed by /help.

Code blocks

• Always wrap code added to a sentence in inline code blocks (`). For example, .gitlab-ci.yml, git add ., CODEOWNERS, or only: [main]. File names, commands, entries, and anything that refers to code should be added to code blocks. To make things easier for the user, always add a full code block for things that can be useful to copy and paste, as they can do it with the button on code blocks.

• HTTP methods (HTTP POST) and HTTP status codes, both full (404 File Not Found) and abbreviated (404), should be wrapped in inline code blocks when used in sentences. For example: Send a DELETE request to delete the runner. Send a POST request to create one.

• Add a blank line above and below code blocks.

• When providing a shell command and its output, prefix the shell command with $ and leave a blank line between the command and the output.

• When providing a command without output, don’t prefix the shell command with $.

• If you need to include triple backticks inside a code block, use four backticks for the code block fences instead of three.

• For regular fenced code blocks, always use a highlighting class corresponding to the language for better readability. Examples:

  ```ruby
  Ruby code
  ```
  
  ```javascript
  JavaScript code
  ```
  
  ```markdown
  [Markdown code example](example.md)
  ```
  
  ```plaintext
  Code or text for which no specific highlighting class is available.
  ```
  

Syntax highlighting is required for fenced code blocks added to the GitLab documentation. Refer to this table for the most common language classes, or check the complete list of available language classes:

For a complete reference on code blocks, see the Kramdown guide.

GitLab SVG icons

Introduced in GitLab 12.7.

You can use icons from the GitLab SVG library directly in the documentation.

This way, you can achieve a consistent look when writing about interacting with GitLab user interface elements.

Usage examples:

• Icon with default size (16px): **{icon-name}**

  Example: **{tanuki}** renders as: {tanuki}.

• Icon with custom size: **{icon-name, size}**

  Available sizes (in pixels): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72

  Example: **{tanuki, 24}** renders as: {tanuki, 24}.

• Icon with custom size and class: **{icon-name, size, class-name}**.

  You can access any class available to this element in GitLab documentation CSS.

  Example with float-right, a Bootstrap utility class: **{tanuki, 32, float-right}** renders as: {tanuki, 32, float-right}

When to use icons

Icons should be used sparingly, and only in ways that aid and do not hinder the readability of the text.

For example, this Markdown adds little to the accompanying text:

1. Go to **{home}** **Project information > Details**.

1. Go to {home} Project information > Details.

However, these tables might help the reader connect the text to the user interface:

| Section                  | Description                                                                                                                 |
|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------|
| **{overview}** Overview  | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers.                      |
| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. |
| **{messages}** Messages  | Send and manage broadcast messages for your users.                                                                          |

Use an icon when you find yourself having to describe an interface element. For example:

• Do: Select the Admin Area icon ( {admin} ).
• Don’t: Select the Admin Area icon (the wrench icon).

Alert boxes

Use alert boxes to call attention to information.

Alert boxes are generated when one of these words is followed by a line break:

• FLAG:
• NOTE:
• WARNING:

For example:

NOTE:
This is something to note.

To display an alert box for multiple paragraphs, lists, or headers, use blockquotes instead.

Alert boxes render only on the GitLab documentation site (https://docs.gitlab.com). In the GitLab product help, alert boxes appear as plain text.

Flag

Use this alert type to describe a feature’s availability. For information about how to format FLAG alerts, see Document features deployed behind feature flags.

Note

Use notes sparingly. Too many notes can make topics difficult to scan.

Instead of adding a note:

• Re-write the sentence as part of a paragraph.
• Put the information into its own paragraph.
• Put the content under a new subheading.

If you must use a note, use this format:

NOTE:
This is something to note.

It renders on the GitLab documentation site as:

NOTE: This is something to note.

Warning

Use a warning to indicate deprecated features, or to provide a warning about procedures that have the potential for data loss.

WARNING:
This is something to be warned about.

It renders on the GitLab documentation site as:

WARNING: This is something to be warned about.

Blockquotes

For highlighting a text inside a blockquote, use this format:

> This is a blockquote.

It renders on the GitLab documentation site as:

This is a blockquote.

If the text spans multiple lines, you can split them.

For multiple paragraphs, use the symbol > before every line:

> This is the first paragraph.
>
> This is the second paragraph.
>
> - This is a list item
> - Second item in the list

It renders on the GitLab documentation site as:

This is the first paragraph.

This is the second paragraph.

• This is a list item
• Second item in the list