Documentation Style Guide
Documentation writer style guide
The Jenkins X Documentation Special Interest Group (SIG) has established some guidelines for docs contribution. The following are not meant to be exhaustive, but are simple style and technical tips to help conform to the existing voice and technical writing techniques used in our existing docs content.
Writer voice and tone
Pages should have titles, and should be descriptive enough on its own that readers (and web search crawlers) can pick up the title without too much missing context. Proper nouns should be capitalized in titles but nothing else (for example, write “Jenkins X tips and tricks” instead of “Jenkins X Tips And Tricks”)
Do not use commands as verbs. For example write “Change to a new directory with
cd” instead of “cd to the new directory”
Use active voice wherever possible instead of passive voice to make explanations and procedures clearer and more direct. For example, write “Click the
TLS/SSLcheckbox if you want to enable a secure connection” instead of “If you want a secure connection to be enabled, make sure the
TLS/SSLcheckbox is clicked.”
When introducing a new acronym to your content, write the full term first before using the acronym (for example, “User Interface (UI)”). Then you can use the acronym in subsequent mentions.
Keep content focus as narrow and prescriptive as possible; no long explanations for actions or drawn out introductions unless describing it in detail for an
Write in one sentence per line, even if you are writing a multi-sentence paragraph. That way when you or other writers are making changes to the content, it will be easier for reviewers to find what has changed in one sentence rather than finding it in a long paragraph.
Use multiples of 10 when assigning the
weightof a new page of content, as it will be easier to prioritize pages within a navigation menu. Let’s say you have 3 existing pages with a
Using this method, a writer can create a page with a weight of
11that will appear between the page weighted
20in the navigation menu.
Use backticks when describing commands, directory paths, or filenames. For example: “Open a terminal and type `cd /usr/local/bin` to find the `jx` command.”
Code blocks should use triple backticks plus the supported code descriptor for proper syntax highlights (for example,
\``bash` for a command run at terminal shell prompt).
Commands to be typed out by the user should not use prompts like
>as they can introduce unintended errors when used with the command.
Use absolute paths when cross-linking content. For example, use
Place the title of your content in the header/metadata of the page under
Title:. Subsequent sections created in the content begin with section 2 header designation (
##) or more.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.