| description |
|---|
How to write docs, when to write them, and where to place them. |
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.
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.
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:
- vscode-markdownlint (for in-line markdownlint feedback)
- Markdown All in One (for convenient keyboard shortcuts, such as
Ctrl + Bfor bold text) - VScode Paste Image (to enable
Ctrl+Alt+Vto paste images from your clipboard to the document and the filesystem)
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.
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.
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.
You can write documentation for these categories, which correspond to 3 groups in the summary file:
- Introductory content: Cover the high-level aspects of a topic and answer common questions in a quick, efficient manner.
- 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.
- 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.
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 semantic line breaks (sembr.org), requiring each sentence written in Markdown to be on its own line.
- Capitalization should follow commonly accepted English guidelines. For example, a capital letter should be used to signal the start of a new sentence, differentiate titles and major headings from the body of the text (using title case), and show proper nouns and product names.
- 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.
- Avoid referring to Opstrace as a "cluster". Instead, prefer referring to an Opstrace instance, an Opstrace installation, or simply by the proper noun Opstrace. For example: log in to the Opstrace instance or 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.