GitLab's general communications practices are detailed at GitLab Communication, but beyond those we do have some channel-specific guidance available. This page is for Handbook-specific guidance that does not necessarily apply to the company overall or to other specific channels such as GitLab Documentation or the GitLab Blog.
In the absence of Handbook-specific guidance, you can't go wrong by following GitLab's Writing Style Guidelines and Documentation Style Guide. The GitLab Documentation site also offers a list of topic-specific style guides.
So what is style? Is it aesthetics? Information architecture? Interaction design? Technical implementation conventions? It can be all of these things, but we'll start this style guide with some information about common elements and tasks.
Content headings should be descriptive enough to suggest their corresponding content when they or corresponding fragment identifiers are seen out of context.
Content headings should be second-level headings and below. First-level headings are reserved for page titles.
Fragment identifiers are automatically generated from most headings. Keep that in mind when choosing your headings.
Handbook content currently uses both
Title Case and
Sentence case for titles and headlines. While sentence case can be a nice design option, title case can actually convey important information independent of punctuation, typographic emphasis, or additional descriptive text—it says this text is the name of something all by itself. That might seem obvious from the styling of a title or a heading, but it isn't obvious in references from other contexts, such as links from other pages, of which there are many in the Handbook. Thus, title case should be preferred over sentence case for Handbook titles and headings. Note that the GitLab Blog uses sentence case, but that is a different context and the Blog is not as reference-heavy as the Handbook.
Brand names such as "Apple" and "Slack" are proper nouns, so they should usually be capitalized. If a brand name uses unusual capitalization, as in "eBay" and "VMware", then follow the brand's convention.
For easy reading, easy typing, and consistency use kebab case—lowercase letters with hyphens between words—for all file and directory names unless you have a specific reason for doing otherwise (e.g., due to a programming convention for which underscores are preferred or because a file is primarily intended for download and you want it to have a certain name when downloaded).
See URL Guidelines for more information about best practices for URLs.
Links from the Handbook should conform to a few general guidelines:
See Understanding Absolute and Relative URLs for more information about each type of URL.
In general, Handbook URLs should describe their content and be as clean and easy to remember as feasible. Unless there is a good reason for formatting URLs otherwise (e.g., language conventions or technical limitations), they should be entirely lower case, any two words should be separated by a single hyphen, and ampersands should be replaced by "and", not an additional hyphen.
Files and directories should never be given names that differ from the names of other files or directories in the same location only by letter case. Case-sensitive file systems allow such naming, but our source code is shared with people using various different file systems, including case-_insensitive_ file systems, upon which the mere existence such similarly named files in a repository can cause problems. For example, new macOS systems use case-insensitive APFS by default and on those systems Git can end up alternately showing two differently-capitalized files as modified when no changes have actually been made to either.
When you’re adding or editing links in the Handbook (or really, anywhere on the marketing site) please keep in mind that root-relative URLs are preferable for our same-site links.
Absolute URLs are the ones that look like this:
With absolute URLs links always load the live version of the site—even when run from a development, testing, or staging context. They're great for sharing URLs via Slack, issue and merge request comments, email, and social media, but not for same-site links.
Document-relative URLs are the ones that look like this:
With document-relative URLs links can break when either a linking document or a linked document is moved separately from the other document. These kinds of URLs can be great for maintaining relationships between documents in different contexts, but links that use this kind of URL are best managed by automated systems that won't forget to update them.
Root-relative URLs, the kind we prefer for use in the Handbook, look like this:
With root-relative URLs same-site links can work properly during local development and testing, during automated tests and staging, and on the live site. And unlike with links that use document-relative URLs, moving a document won't break its same-site links to other pages that do not move with it.