Book: SE@Google Ch15: Documentation

[cedricongjh]

Book: Software Engineering at Google
Chapter: 15

Summary:

• Types of Documentation: Documentation encompasses all supplementary texts engineers need, including standalone documents and code comments, with a significant portion at Google being in the form of code comments.

• Importance of Documentation: Quality documentation yields numerous benefits for engineering organizations, such as enhancing code comprehension, clarifying design goals, streamlining manual processes, and facilitating onboarding of new team members. Although its benefits may not be immediately apparent to the author, investing in documentation pays off over time through increased code readability, reduced errors, and smoother collaboration.

• Challenges and Benefits to Authors: Despite its importance, documentation is often undervalued or considered burdensome by engineers. Challenges include viewing writing as a separate skill from programming, feeling inadequate as writers, limited tool support, and perceiving documentation as extra maintenance. However, documentation offers benefits to authors, including aiding in API formulation, providing a roadmap for maintenance, enhancing code professionalism, and reducing the need for repeated explanations.

• Documentation as Code: Documentation should be treated like code. This involves applying similar principles and practices, including establishing internal policies, placing it under source control, assigning clear ownership, conducting reviews for changes, tracking issues, and periodically evaluating its accuracy and freshness. By integrating documentation into existing developer workflows and tools, engineers can minimize upfront costs and maximize long-term benefits, fostering a culture where documentation is valued as an integral aspect of software development.

• Understanding and Addressing Audience Diversity: Engineers often make the mistake of writing documentation solely for themselves, which can lead to assumptions that don't hold for a wider audience. It's crucial to identify the diverse audience(s) your documentation needs to serve based on criteria like experience level, domain knowledge, and purpose. By tailoring documentation to different audience groups and writing in a style that applies broadly, you ensure clarity and relevance for both experts and novices.

• Audience Encounter Distinction: How users encounter documentation—either as "seekers" who know what they're looking for or as "stumblers" who need guidance—is essential for crafting effective documentation. Seekers benefit from consistency in format for easy reference, while stumblers require clarity and overviews to navigate unfamiliar territory. Additionally, distinguishing between customer and provider audiences helps streamline documentation, ensuring that implementation details are appropriately segregated from end-user-facing information, documentation should differ for different audiences

TLDR:

• Documentation is hugely important over time and scale.
• Documentation changes should leverage the existing developer workflow.
• Keep documents focused on one purpose.
• Write for your audience, not yourself