How to Create Good Documentation

TL;DR: Effective documentation is essential for knowledge sharing, tracking progress, and aligning teams. At Doppler, we categorize documentation into Living Docs and Artifacts to manage them efficiently. Living Docs are regularly updated and evolve with our projects, while Artifacts capture specific moments in time and generally remain static. Our best practices include proactive maintenance, logical structuring, and maintaining openness to ensure documentation is current, accessible, and valuable. We prioritize these strategies to enhance operational efficiency and foster a collaborative, informed culture.

How We Do Documentation

Using documentation effectively can often be a challenging aspect for any engineering team. At Doppler, We've developed an approach to documentation that suits our needs, though we recognize that our practices may not be one-size-fits-all.

Whether you are part of a small startup or a large enterprise, the insights shared here may help you refine your documentation strategy better to meet the challenges of your projects and team dynamics.

Purpose of Documentation

Before we discuss the specifics of our documentation strategy at Doppler, it's essential to understand why documentation is an indispensable part of our engineering culture.

Knowledge Sharing and Transfer

Documentation is a comprehensive knowledge repository encompassing detailed information about our processes, decisions, insights, and learnings. This is invaluable for:

• Onboarding new team members: Documentation provides a thorough overview, accelerating the ramp-up process.
• Bringing team members up to speed: Documentation offers a quick way to acquire the necessary context, whether someone is transitioning roles or projects.
• General inquiries: It serves as the first point of reference for questions like, "How does this system work?" or "What was the rationale behind this architectural choice?"

Reference Material

Our documentation is also a critical reference tool, allowing team members to:

• Cite historical decisions: Understanding the 'why' behind past decisions helps shape future strategies.
• Standard procedures: It offers guidance on standard practices and syntax, answering queries such as, "What’s the procedure for deploying this service?"

Progress Tracking

As projects evolve, so does the associated documentation. It provides a living record of:

• Project evolution: Documentation details the progression, changes, and decision-making processes throughout a project’s lifecycle.
• Retrospective analysis: After a project's completion, documentation helps assess what went well or what could be improved by answering questions like, "Why was this approach chosen over that one?"

Communication Tool

Documentation is a communication tool that aligns stakeholders by:

• Centralizing communication: It provides a platform for discussing ideas, concerns, and decisions.
• Facilitating clarity and consensus: It helps clarify processes and ensure that all team members are on the same page with queries such as, "How do we implement this feature?"

By recognizing the diverse purposes of our documentation, we can better appreciate its role in fostering an informed, efficient, and cohesive engineering team.

Types of Documentation

We categorize our documentation into two primary types to keep our information organized and accessible. Understanding these categories helps our team members know how to create, maintain, and use documentation effectively.

Living Docs

Living Docs are dynamic and evolve as our knowledge and projects develop. They are not just records but tools that grow with us:

• Continually updated: As new insights emerge or processes change, these documents are updated to reflect the latest information.
• Maintenance and accuracy: While they require ongoing attention, the effort is justified by the value they provide in maintaining current, accurate information.
• Version control: For documents with significant historical value, such as architecture decisions or detailed project timelines, we use tools like Git. This allows us to track changes and understand the evolution of our thinking and project direction.
• Integration with code: For technical documentation that directly relates to code, such as API documentation or in-code annotations, we store documents alongside the codebase. Engineers are more likely to find and benefit from documentation living within the codebase. This practice ensures that changes in code and documentation are synchronized, enhancing coherence and reducing discrepancies.

Examples of Living Docs:

• Architecture Documents
• Project Deployment Lifecycle
• In-code documentation like Project Gotchas and Optimization Opportunities

Artifacts

Artifacts, in contrast, are typically static documents created as a byproduct of meetings, investigations, or any other discrete activities:

• Point-in-time knowledge: They capture the state of knowledge at a particular moment and are not intended to be updated regularly.
• Lower maintenance: Once created, these documents do not usually require updates, but they may be marked as obsolete or superseded as needed.
• Brevity and utility: Even brief or incomplete artifacts can provide valuable insights. They serve as a reference point for future activities and decision-making processes.

Examples of Artifacts:

• Meeting Notes
• Third-Party Integration Gotchas
• System Design Proposals / RFCs
• Documentation of Observed Anomalies or Behaviors

By distinguishing between Living Docs and Artifacts, we ensure that our documentation efforts are as efficient and effective as possible, tailored to the nature of the information and its intended use within our organization.

Our Best Practices at Doppler

Here are some of the best practices we've implemented to manage our documentation effectively:

Proactive Maintenance

• Updating and Correcting Information: Encourage team members to update documents as they find outdated or incorrect information. This practice not only keeps our documentation relevant but also empowers our team to contribute to the collective knowledge base.
• Periodic Reviews: Assign responsibility to individuals or teams to review documents regularly. This ensures that no document becomes obsolete unnoticed, maintaining the integrity and utility of our informational resources.

Dynamic Document Lifecycle

• Transitioning Artifacts to Living Docs: Occasionally, what starts as an artifact (like a System Design Proposal / RFC) proves so valuable that it evolves into a living document. It then continues to be updated as the project develops, preserving its relevance and expanding its utility.
• Converting Living Docs to Artifacts: Conversely, documentation for systems or processes that become outdated is not discarded but marked as stale and kept as a historical reference. Adding notes about why a process was abandoned or what has replaced it can provide valuable insights for future decision-making.

Organization and Accessibility

• Logical Structuring: Create specific folders or databases to house different types of documents. This helps organize the documentation and makes it easier for everyone to find and access the necessary information.
  • General Documentation: A "Meetings Notes" folder can be placed alongside project-specific documentation.
  • Engineering Documentation: Set up folders like "Internal Blog," "System Designs," "Spikes," and "Investigations" to cater to various engineering needs.
• Maintaining Openness: Keep information as public as possible within the organization. The more accessible the documentation, the more likely it is to be helpful to someone, perhaps in unexpected ways.

By adhering to these best practices, we ensure that our documentation is not only comprehensive and current but also a robust tool that supports our ongoing operations and fosters a collaborative and informed workplace culture.

Key Takeaways

Documentation is not merely about keeping records; it's a crucial element of knowledge management that, when done correctly, significantly enhances operational efficiency and team cohesion. Here are the key takeaways from our approach at Doppler:

Prioritize Effective Documentation Types

• Leverage Artifacts for Immediate Needs: Utilize artifacts to capture decisions and discussions. These documents are quick to produce and provide immediate value, ensuring that even fleeting insights are preserved.
• Invest in Living Docs for Long-term Value: Though more resource-intensive, living docs offer substantial long-term benefits. They evolve with the project, providing a reliable, up-to-date resource that supports both current needs and future retrospectives.

Maintain Documentation Diligently

• Prompt Updates: Encourage team members to update documentation as soon as discrepancies are noticed. This minimizes the spread of outdated or incorrect information.
• Regular Reviews: Establish a routine for reviewing living documents to ensure their accuracy and relevance over time. This could involve assigning specific review responsibilities to designated team members or teams.

Enhance Accessibility

• Integration with Code Repositories: For technical documents, especially those that track with code development, store these documents in the same repositories as the code. This practice helps maintain version coherence between documentation and code changes.
• Open Documentation Practices: Strive to keep documentation as open and accessible as possible within the organization. This transparency facilitates better information flow and builds a culture of knowledge sharing.

By adhering to these principles, we ensure that our documentation is an invaluable asset to the organization, fostering our culture of continuous learning and improvement. The goal is not just storing information but actively enhancing our collective understanding and operational efficiency.

If you like this post, you might also like our post about how we use Code Review Comment Prefixes for Clearer Feedback.