3.9 KiB
id, revision, hide
| id | revision | hide | |
|---|---|---|---|
| 12 | 4 |
|
Style guidelines
Approach
User experience is at the heart of what we write. We write documentation to help users achieve their goals, overcome roadblocks, and encourage them to explore the Status app. In addition, we provide ways for readers to [submit feedback :octicons-tab-external-16:][contributors-guide], and we constantly improve our documents based on this feedback.
When deciding what to write, we're user-oriented. And when designing documents, we're task-oriented, explaining the main tasks a user can complete on a particular screen or product feature.
We describe the user's tasks on the interface; we don't explain the user interface. We work with the Design and UX team to provide users with a modern and consistent experience in our app and documentation.
We use the topic and article words indistinctly on this guide. Even though the definition of a topic in technical communication varies based on the methodology or author, this distinction is irrelevant here.
Content structure
How we structure and present the information is just as critical as writing it. Users don't read documentation; they scan it. Our approach to content structure supports them in this workflow rather than getting in the way.
Many style guides spend considerable time explaining language style and grammar rules. Still, they rarely provide guidelines to create easy-to-read and follow documents consistently. Because of this, this style guide offers detailed instructions for structuring your content.
We employ a progressive-disclosure approach, providing only the necessary information at the first level (usually, a task or a concept description) while allowing users to explore additional details at subsequent levels (subtasks, cross-links, table of contents, and so forth).
We use a topic-based approach based on [DITA][DITA] and well-established information design patterns, where each type of article adheres to a specific structure. However, we don't follow (nor want to follow) a strict DITA approach to documentation.
Writing style
When creating technical content for Status, consider these guidelines:
- Write in a friendly, casual, and human tone without sounding bossy, informal, or funny.
- Write declarative and straightforward prose with short sentences and paragraphs, and use everyday vocabulary. Don't make things any more complicated than they are. Write as you speak.
- Make every word matter. Avoid words or constructions that make a text harder to read or obfuscate information or the meaning of a sentence. Be precise.
- Use you or your to address the user. The user and user's goals are at the center of the action, not the software.
- Don't use cultural or local expressions, made-up words, figurative language, obscure acronyms, metaphors, or (needless to say) discriminatory language. Write for a general audience without considering factors such as race, ethnicity, religion, nationality, or gender.
- Don't assume the reader has prior knowledge of a new concept when introducing it. Instead, explain the idea in simple terms and provide readers with resources or related topics to find out more.
- Use a positive tone. Technical documentation should present information in a positive and helpful manner. Instead of describing what a product or feature can't do, focus on what it can do. This will help users understand the capabilities and benefits of the product or feature.
- We don't obsess over grammar rules. Language isn't an exact science, and different style guides use different conventions. This guide follows the rule commonly accepted, disregarding exceptions.
- Status documentation should be written in Global English using Oxford spelling.
[:octicons-git-branch-24: Contribute to our docs][contributors-guide]{ .md-button }
--8<-- "includes/urls-style-guide.txt"