Project: Opstrace (Observability and Analysis / Observability)
File: writing-docs.md

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 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 youll enjoy working with the following extensions. They simply make it easier and faster to write Markdown: (for in-line markdownlint feedback) (for convenient keyboard shortcuts, such as `Ctrl + B` for bold text) (to enable `Ctrl` + `Alt` + `V` to 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: . When your peers will be reading your documentation, you want it to be the best it can be. We recommend using 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 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

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 usedthis 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 , requiring each sentence written in Markdown to be on its own line. Capitalization should follow . 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 ), and show 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. () 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. 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 . Alternatives may include italicization or capitalization. When in doubt, use quotation marks sparingly.