We are thrilled at Better Stack to continue expanding our collection of technical articles centered around building, scaling and observing production applications to improve reliability. To maintain a consistent style and quality across all our articles, we’ve devised the guidelines contained in this document. Please read it in its entirety before you begin to work on your article. This will help us review your drafts and get to the publication stage much quicker.

We try to distinguish ourselves from other publications in the following ways:

1. In-depth articles.
2. High quality technical explanations.
3. Practical examples and engaging demos.

Style

Our aim is to produce the best content on whatever subject we are publishing and provide practical information for the developers, engineers, and executives that will be reading our articles. To this effect, we’ve come up with the following rules:

1. Don’t assume anything about the reader’s background knowledge. Keep in mind that readers are often new to the subject they are reading about, and just because something is obvious to you doesn’t mean it will be obvious to someone else.
2. Present the background information that readers need to complete the tutorial in the Prerequisites section.
3. Include every command or code snippet that is necessary to understand the concepts or steps being discussed in the article.
4. Provide sufficient explanation for each command or code snippet that’s included in the article. Ensure that the reader understands why a code snippet or command is needed, and not just how it is executed.
5. Ensure that all the code and commands used in the tutorial are well tested and produce the output specified in the tutorial using the correct version of the respective tool or language in use.
   • Note that our editors are also technical. They’ll follow the tutorial as written during the review process and deviations from the expected result will be called out during review.
6. We emphasize a practical approach where you adequately demonstrate the concepts you’re describing with hands-on examples that readers can translate to solving real-world problems.
7. Document your sources. Where possible, link to existing Better Stack content but feel free to link to outside sources too (as long as they’re not a competitor to Better Stack). Always let your readers know where your information is coming from. Prefer official documentation or authoritative sources that are correct and likely to stay up to date over time.
8. The overall voice of an article should be friendly, but authoritative. Do your research, and let it show. Let your claims be well-informed and justifiable.
9. Don’t include memes, jargon, unrelated images or animated GIFS, and any other irrelevant content in the article.
10. Acronyms should be spelled out on their first use, except for the most common and obvious ones such as HTTP or HTML.
11. Always address the reader directly using the second person pronoun “you”.
    • "Developers have the freedom to experiment with different coding techniques to achieve their desired outcome.” ❌
    • "You have the freedom to experiment with different coding techniques to achieve your desired outcome.” ✅
12. Avoid language that may be deemed offensive.