Writing Guidelines

Technical documentation serves diverse audiences with different needs and expertise levels. Unlike user experience design focusing on personas, documentation writing centers on roles aligning with specific actions and goals (user intents).

Two fundamental roles shape how users interact with technical documentation:

The Consumer Role represents users who need to accomplish specific tasks with the product. These users require clear, action-oriented documentation that helps them achieve their goals efficiently.
The Contributor Role encompasses advanced users who extend and enhance the product's capabilities, requiring more detailed technical information and architectural understanding.

For example, products like Backstage.io caters to both consumers and contributors. Therefore, documentation must address the unique needs of each role effectively.

Documentation for consumers

Consumers are end users who interact with the product as part of their daily workflows. Their primary focus is on using the product effectively to complete their work. Consumer documentation should emphasize clarity, simplicity, and task completion.

Their responsibilities typically include using core product features, working with templates, and utilizing search and organization features. When writing for consumers, focus on providing context-rich instructions that guide users through common tasks while avoiding unnecessary technical complexity.

Documentation for consumers should establish a clear path from beginning to end for each task. Writers should anticipate common questions and provide answers within the natural flow of the content. Use consistent terminology and sufficient context to help users understand the how and why of each step.

Documentation for contributors

Contributors represent advanced users who actively participate in expanding the product's capabilities. These power users need comprehensive technical information to develop new features, create templates, and enhance existing functionality.

Their activities often involve template development, plugin creation, documentation improvements, and setting up a local development environment. Contributor documentation requires greater technical depth, including architectural details, API specifications, and development guidelines.

When writing for contributors, maintain technical accuracy while thoroughly explaining complex systems. Include detailed configuration examples, troubleshooting guides, and explanations of internal architectures. This documentation should enable contributors to make informed decisions about implementation approaches.

Writing for technical documentation

Creating effective technical documentation requires a careful balance between clarity and depth. Writers should consider the following core principles:

For Consumer Documentation

Begin with clear prerequisites and system requirements—present information in a logical sequence that builds understanding progressively. Include practical examples that demonstrate real-world usage. Provide troubleshooting guidance for common issues. Minimize technical jargon and define essential technical terms when they first appear.

For Contributor Documentation

Establish a solid technical foundation before advancing to complex topics. Include detailed architecture and design explanations. Provide extensive code examples with thorough comments. Document edge cases and potential pitfalls. Maintain comprehensive API documentation with usage examples.

The effectiveness of technical documentation depends on its ability to serve consumers and contributors appropriately. Writers should regularly review and update documentation to ensure it remains relevant and accurate as the product evolves.

Successful technical documentation anticipates user needs, provides appropriate detail for each role, and maintains a consistent structure. While perfection may be aspirational, continuous improvement through regular updates and refinements helps maintain documentation quality and usefulness.

tip

Remember that documentation quality directly impacts product adoption and user success. Regular feedback from both consumers and contributors helps identify areas for improvement and ensures that documentation continues to meet user needs effectively.

Focus on the user intent

As a user, I want < what? > because/so that < why? >.

When users consult technical documentation, they have a specific purpose in mind. Determine the specific task (goal or scenario) the user is trying to accomplish and adjust the tone accordingly.

Write brief, meaningful, and focused text

Be clear and concise, especially in instructions.

Lead with what matters most so readers can immediately focus their attention. Be direct and avoid unnecessary words. Keep sentences short and to the point. Focus your content on user scenarios or goals rather than on product features.

User-focused: On the Replicator page, you can synchronize your local database with replica databases.
Product-focused: The Replicator page lets you synchronize your local database with replica databases.

Aim for conciseness by presenting all necessary information clearly and briefly. Avoid irrelevant details that might distract or confuse readers.

Plain language benefits everyone, including experts!

Clear communication is a responsibility you have to your readers.

Remember, the main purpose of communication is to convey information. Use words in your content that match what people search for.

Strive for a 10th to 12th-grade reading level. The content above this level demands excessive mental effort. For more insights, see Legibility, Readability, and Comprehension: Making Users Read Your Words.

Using direct, simple language isn't condescending—effective communication makes content quicker and easier to understand.

Write Concisely

Long text can overwhelm users, prompting them to skip content or seek answers elsewhere.

While content contributors are advised to be concise, achieving this can be challenging.

Aim to create just enough documentation to be helpful, prioritizing clarity and usefulness over exhaustive detail. This lean approach remains manageable. Our goal is to assist users, not overwhelm them with essay-like content.

When striving for brevity, ask yourself: Is this essential for the reader's understanding? This question guides you in cases where clarity must take precedence over brevity. Sometimes, concepts require more explanation.

Here are additional strategies to reduce word count and enhance content scanability:

Bullet points and lists: Break down complex ideas into digestible pieces, making it easier for readers to locate specific details.
Tables: Present data in a clear, logical layout for quick comprehension. Keep tables simple, focusing on essential information. Avoid over-complexity, as it can be counterproductive.
Concise sentences and paragraphs: Aim for sentences of 20 words or fewer. Focus each paragraph on a single idea or concept to make the document less daunting.
Clear headings and subheadings: Use these as signposts to indicate section content.
Edit ruthlessly: Eliminate redundancy and unnecessary words. Ensure each sentence adds new information.
Key information first: Use the 'inverted pyramid' style to present crucial points upfront. Learn more about inverted pyramid writing.
Use white space: Incorporate adequate spacing around text and between sections to reduce clutter and improve readability.

Enhance readability and user engagement

Use active voice, present tense, and second person ("you"). Active voice makes your writing livelier and more concise than passive constructions. The second-person point of view directly addresses the reader, creating a more engaging and personal tone.

Provide common real-life scenarios or examples

Illustrate how to apply the information using relatable scenarios. Focus on addressing users' specific tasks, problems, or questions to meet their needs effectively.

Use visual elements

Incorporate diagrams, charts, infographics, or images to convey complex information concisely. Visual elements can often communicate ideas more effectively than text alone, saving space and enhancing understanding.

Make your content easy to scan

Readers typically scan content rather than reading every word.

They aim to be efficient, doing the least work necessary to achieve their goal. A report by Nielsen Norman Group identified four main text scanning patterns:

F-pattern — Without subheadings and bullets, users focus on words at the beginning of lines and top of the page.
Spotted pattern — Users fixate on specific words or phrases throughout the page.
Layer-cake pattern — Readers focus on the page's headings and subheadings.
Commitment pattern — Traditional reading of most or all words, leading to best comprehension but taking the most time.

To accommodate these patterns, prioritize important information, use tables and bullet lists, create descriptive headings and subheadings, and include visuals like diagrams and infographics. This approach quickly conveys key points and caters to various reading styles.

For more strategies on enhancing content scannability, refer to the Content structure and organization section.

Use notes, cautions, and tips sparingly

Keep these elements concise and relevant to avoid overwhelming the reader.

Each note, caution, or tip should directly support the surrounding content.

Place these elements strategically, much like in a cooking recipe. For instance, include a note about a specific step right where it's needed, not at the end or in a separate section. This ensures users have crucial information at the right moment—similar to how a baker needs ingredient substitution details while measuring, not after finishing the recipe.