Writing documentation

We invite you to help us build a comprehensive library of world-class documentation. With your enthusiasm and expertise, everyone in the Opstrace community will benefit.

Get on your marks

Before your start crafting lovely sentences, keep these thoughts in mind:

  • We encourage you to modify any Markdown doc you want as part of your PR. This ultimately allows you to create fresh and practical documentation.
  • GitHub is the source of truth for our documents.
  • We use markdownlint to define our canonical document style. Run the following to ensure your changes will pass CI: make lint-docs.

Your toolkit (how to edit docs)

You can edit the Markdown files using your favorite editor. Please find some recommendations for doing this below.

We suggest that you use VS Code. And if you like using that, we suspect you’ll enjoy working with the following extensions. They simply make it easier and faster to write Markdown:

You might find it helpful to use the native VS Code "Open Preview to the Side" feature (Ctrl + K + V). That said, we prefer to use the following extension to style its output more like GitHub: Markdown Preview Github Styling.

Keep it clean

When your peers will be reading your documentation, you want it to be the best it can be. We recommend using Grammarly to check for clarity, grammar, and proper word usage. Hey, even professional technical writers need another set of eyes.

When to update docs

Ideally, docs is updated in the same pull request that also contains the corresponding code changes. Of course, some documents may not require updating. See our pull request template to better assess what may or may not need updates.

The doc creation possibilities

You can write documentation for these categories, which correspond to 3 groups in the summary file:

  1. Introductory content: Cover the high-level aspects of a topic and answer common questions in a quick, efficient manner.
  2. Guides: Walk readers through specific, goal-based tasks. These documents are meant to be read from beginning to end, so they should contain all of the necessary information for the specific task.
  3. Reference documents: Help developers locate the information they need to accomplish specific tasks. Typically, you organize content in lists rather than with formal sentences and paragraphs.

Notes on style

Rather than adopt a single style wholesale, here we iteratively build up our own style guidelines for writing docs by collecting the best ideas from our community over time. That being said, we tend to follow the most common American English usage and idioms, and prefer a casual rather than formal tone. If you have a suggestion, please open a PR to start the conversation.

As hinted at in the previous section, the guides and intro documents (e.g. quick start) should be written in a casual, conversational style. This includes a variety of sentence structures, word choices, etc. It also informs decisions such as using the common form of the word “data” (which takes many forms: singular noun, plural now, mass noun… probably some other things…). The reference documents should be written in very clear and concise terms, with as few words as possible. They are meant to be linked into, rather than read all the way through. All that being said, proper grammar and punctuation should always be used—this will be the one constant across all of the docs.

Here is a laundry list of various style, grammar, and other choices we've made over time:

  • We follow sembr.org, requiring each sentence written in Markdown to be on its own line.
  • Use title case for top-level headings (h1); use sentence case for all other headings.
  • Use colons when introducing a block quote or code block.
  • Use the verb log in to over log into or login to; as a noun, use login. (Reference)
  • Prefer the singular use of data, as in this data.
  • Prefer the phrase the cluster or the Opstrace cluster over other phrases such as send data to Opstrace.
  • Quotation marks can be tricky to use in English: use them for quotations, highlighting unusual usage, an invented term, or calling out someone else's terms; do not use them for irony or emphasis, and beware of the downsides of scare quotes. Alternatives may include italicization or capitalization. When in doubt, use quotation marks sparingly.
  • Capitalization should be used to signal the start of a new sentence, differentiate titles and major headings from the body of the text, and show proper nouns and official titles.