Vultr's documentation library contains hundreds of articles written by many authors. Documentation should be clear and easy to understand, without needless slang and jargon. Just as programmers need reference material when writing software, authors need guidelines for style, formatting, and vocabulary. This quick start guide is a short reference with links to more comprehensive information.
Break your documentation into logical sections. Use H2 for major section headers, and preface your H2 sections with step numbers (use numerals, not words) and colons as shown. Use title case for H2 headings. We prefer titles formatted according to the Chicago Manual of Style. If you aren't sure about your title format, try the Capitalize My Title tool.
Each major H2 section may also contain multiple subsections. Use H3 for subsections, and format them in sentence case. Subsections usually don't have punctuation.
Active voice instructions are usually shorter and easier to understand.
Documentation is not a blog post. Short sentences and fragments are better suited for documentation than long narratives. At the same time, documentation should explain the steps. It's insufficient to simply paste a block of code and instruct the reader to run it.
For example, replace this:
The first of the tables that we will create will be the /etc/credentials file. As the name suggests, this will be holding the username and password of each virtual mail account. If you notice from the smtpd configuration file, this is of type passwd. We do this so that OpenSMTPD and Dovecot can share an authentication database and save administration headaches further on down the line.
OpenSMTPD and Dovecot share the passwd format authentication database /etc/credentials.
When faced with a choice, give the reader enough information to make a confident decision, but don't overload them with options. It's not required to explain every possible setting. Give the reader sane defaults for a basic configuration.
It's common to omit "you" and "you will" in instructional steps. It's implied that the reader is "you".
Documentation must be unambiguous. Use the Oxford Comma to avoid confusion. Compare the following examples:
I love my parents, Batman and Wonder Woman.
Unclear: Their parents are superheroes?
I love my parents, Batman, and Wonder Woman.
The meaning is clear: They love their parents, and love Batman, and also love Wonder Woman.
You have the advantage of knowing how your tutorial works. The reader is inexperienced. Consistent use of the Oxford Comma avoids confusion.
Scan your documentation for the words "I" and "we". Vultr's documentation is a collection of articles written by many authors. There are no individual credits. Likewise, "we" could refer to the author and the reader working together, or it could refer to Vultr. Unless the context of "we" is clear, you should avoid these pronouns.
Avoid weak writing. Most statements should start with a verb. Avoid "you can", "there is", "there are", "there were".
Grammar-check software isn't perfect, but it it's useful to flag problems to review. MS Word and Grammarly are two popular options.
Thank you for contributing to our document collection! We aim to be a high-quality resource for the entire Vultr community. If you see an error in our documentation, please use the Suggest an update button at the bottom of every Vultr Doc. If you have a question about the Vulr Docs program, please contact us. We appreciate your feedback.