This in-progress style guide establishes editorial guidelines for anyone who wants to write documentation for Netdata products.
Table of contents
- Goals of the Netdata style guide
- General principles
- Tone and content
- Language and grammar
- Markdown syntax
Proper documentation is essential to the success of any open-source project. Netdata is no different. The health of our monitoring agent and our community depends on this effort.
We're here to make developers, sysadmins, and DevOps engineers better at their jobs, after all!
We welcome contributions to Netdata's documentation. Begin with the contributing to documentation guide, followed by this style guide.
Goals of the Netdata style guide
An editorial style guide establishes standards for writing and maintaining documentation. At Netdata, we focus on the following principles:
- High-quality writing
These principles will make the documentation better for everyone who wants to use Netdata, whether they're a beginner or an expert.
Breaking the rules
None of the rules described in this style guide are absolute. We welcome rule-breaking if it creates better, more accessible documentation.
But be aware that Netdata staff or community members may ask you to justify your rule-breaking during the PR review process.
Yes, this style guide is pretty overwhelming! Establishing standards for a global community is never easy.
Let's start with a few key points to start. Where relevant, these points link to more in-depth information about a given rule.
- Be conversational and friendly.
- Write concisely.
- Don't use words like here when creating hyperlinks.
- Don't mention future releases or features in the documentation.
- Capitalize words at the beginning of sentences, for proper nouns, and at the beginning of document titles and section headers.
- Use second person—"you" rather than "we"—when giving instructions.
- Use active voice to make clear who or what is acting.
- Always employ an Oxford comma on lists.
- Reference UI elements with bold text.
- Use our built-in syntax highlighter to improve the readability and usefulness of code blocks.
- Include alt tags on images.
Tone and content
Netdata's documentation should be conversational, concise, and informational, without feeling overly formal.
By following a few principles on tone and content we'll ensure more readers from every background and skill level will learn as much as possible about Netdata's capabilities.
Conversational and friendly tone
Netdata's documentation should be conversational and friendly. To borrow from Google's fantastic developer style guide:
Try to sound like a knowledgeable friend who understands what the developer wants to do.
Feel free to let some of your personality show! Documentation can be highly professional without being dry, formal, or overly instructive.
You should always try to use as few words as possible to explain a particular feature, configuration, or process. Conciseness leads to more accurate and understandable writing.
Use informational hyperlinks
Hyperlinks should clearly state its destination. Don't use words like "here" to describe where a link will take your reader.
In general, guides should include fewer hyperlinks to keep the reader focused on the task at hand. Documentation should include as many hyperlinks as necessary to provide meaningful context.
Avoid words like "easy" or "simple"
Never assume readers of Netdata documentation are experts in Netdata's inner workings or health monitoring/performance troubleshooting in general.
If you claim that a task is easy and the reader struggles to complete it, you may inadvertently discourage them.
If you perceive one option to be easier than another, be specific about how and why. For example, don't write, "Netdata's one-line installer is the easiest way to install Netdata." Instead, you might want to say, "Netdata's one-line installer requires fewer steps than manually installing from source."
Avoid slang, metaphors, and jargon
A particular word, phrase, or metaphor you're familiar with might not translate well to the other cultures featured among Netdata's global community. We recommended you avoid slang or colloquialisms in your writing.
In addition, don't use abbreviations that have not yet been defined in the document. See our section on abbreviations for more information.
If you must use industry jargon, such as "white-box monitoring," in a document, define the term as clearly and concisely as you can.
White-box monitoring: Monitoring of a system or application based on the metrics it directly exposes, such as logs.
Avoid emojis whenever possible for the same reasons—they can be difficult to understand immediately and don't translate well.
Mentioning future releases or features
Documentation is meant to describe the product as-is, not as it will be or could be in the future. Netdata documentation generally avoids talking about future features or products, even if we know they are inevitable.
An exception can be made for documenting beta features that are subject to change with further development.
Language and grammar
Netdata's documentation should be consistent in the way it uses certain words, phrases, and grammar. The following sections will outline the preferred usage for capitalization, point of view, active voice, and more.
Follow the general English standards for capitalization. In summary:
- Capitalize the first word of every new sentence.
- Don't use uppercase for emphasis. (Netdata is the BEST!)
- Capitalize the names of brands, software, products, and companies according to their official guidelines. (Netdata, Docker, Apache, NGINX)
- Avoid camel case (NetData) or all caps (NETDATA).
Capitalization of 'Netdata' and 'netdata'
Whenever you refer to the company Netdata, Inc., or the open-source monitoring agent the company develops, capitalize Netdata.
However, if you are referring to a process, user, or group on a Linux system, you should not capitalize, as by default
those are typically lowercased. In this case, you should also fence these terms in an inline code block:
Capitalization of 'Agent' and 'Cloud'
Netdata is split into two products: the open source monitoring Agent, and the closed source web application Cloud. Because both Agent and Cloud are formal nouns, you should capitalize them.
Capitalization of document titles and page headings
Document titles and page headings should use sentence case. That means you should only capitalize the first word.
If you need to use the name of a brand, software, product, and company, capitalize it according to their official guidelines.
Also, don't put a period (
.) or colon (
:) at the end of a title or header.
When writing documentation, you should use the second person ("you") to give instructions. When using the second person, you give the impression that you're personally leading your reader through the steps or tips in question.
See how that works? It's a core part of making Netdata's documentation feel welcoming to all.
Avoid using "we," "I," "let's," and "us" in documentation whenever possible.
The "you" pronoun can also be implied, depending on your sentence structure.
Use active voice instead of passive voice, because the active voice is more concise and easier to understand.
When using voice, the subject of the sentence is action. In passive voice, the subject is acted upon. A famous example of passive voice is the phrase "mistakes were made."
Standard American spelling
While the Netdata team is mostly not American, we still aspire to use American spelling whenever possible, as it is the standard for the monitoring industry.
If you want to instruct your reader to take some action in a particular circumstance, such as optional steps, the beginning of the sentence should indicate that circumstance.
By placing the circumstance at the beginning of the sentence, readers can immediately know if they want to read more or follow a link.
The Oxford comma is the comma used after the second-to-last item in a list of three or more items. It appears just before "and" or "or."
Abbreviations (acronyms and initialisms)
Use abbreviations (including acronyms and initialisms) in documentation when one exists, when it's widely accepted within the monitoring/sysadmin community, and when it improves the readability of a document.
When introducing an abbreviation to a document for the first time, give the reader both the spelled-out version and the shortened version at the same time. For example:
After you define an abbreviation, don't switch back and forth—use only the abbreviation for the rest of the document.
You can also use abbreviations in a document's title to keep the title short and relevant. If you do this, you should still introduce the spelled-out name alongside the abbreviation as soon as possible.
The Netdata documentation uses the Markdown syntax for styling and formatting. If you're not familiar with how it works, please read the Markdown introduction post by its creator, followed by Mastering Markdown guide from GitHub.
You can follow the syntax specified in the above resources for the majority of documents, but the following sections specify a few particular use cases.
Linking between documents
Documentation should link to relevant pages whenever it's relevant and provides valuable context to the reader. To
ensure links function properly on both GitHub and our generated documentation on Netdata
Learn, links should always reference the full path to the document, beginning at the root
of the Agent repository (
/). Links should also always end with the filename of the destination document, ending in the
Avoid relative links or traversing up directories using
For example, if you want to link to our installation guide, you should link to
reference the guide for increasing metrics storage, use
References to UI elements
If you need to instruct your reader to click a user interface (UI) element inside of a Netdata interface, you should
reference the label text of the link/button with Markdown's (
**bold text**) tag.
⚠️ Avoid using directional language to orient readers, because not every reader can use instructions like "look at the top-left corner" to find their way around an interface.
If you feel that you must use directional language, perhaps use an image (with proper alt text) instead.
Language-specific syntax highlighting in code blocks
Our documentation site at learn.netdata.cloud uses
Prism for syntax highlighting. Netdata
documentation will use the following for the most part:
go. If no language is specified, Prism tries to guess the language based on its content.
Include the language directly after the three backticks (
```) that start the code block. For highlighting C
code, for example:
And the prettified result:
Prism also supports titles and line highlighting. See the Docusaurus documentation for more information.
⚠️ Line numbers and highlights are not compatible with GitHub's Markdown parser, and thus will only be viewable on our documentation site. They should be used sparingly and only when necessary.
Netdata's documentation should be as accessible as possible to as many people as possible. While the rules about tone and content and language and grammar are helpful to an extent, we also need some additional rules to improve the reading experience for all readers.
We have a few rules around using images. Perhaps most importantly, don't use only images to convey instructions. Each image should be accompanied by alt text and text-based instructions to ensure that every reader can access the information in the best way for them.
Provide alt text for every image you include in Netdata's documentation. It should summarize the intent and content of the image.
In Markdown, use the standard image syntax,
!(/docs/agent/contributing), and place the alt text between the brackets
. Here's an example
using our logo:
Images of text
Don't use images of text, code samples, or terminal output. Instead, put that text content in a code block so that all devices can render it clearly and screen readers can parse it.