Book: SE@Google Ch: 10 - Documentation

[jasonqiu212]

Book: Software Engineering at Google
Chapter: 10 - Documentation

TL;DR:

• Docs are important!
• Treat docs like code
• Keep docs focused one 1 purpose
• Write for your audience

Summary:

• Documentation is vital! but is often overlooked by SWEs
  • For team leads: Instead of forcing SWEs to become technical writers, think about how to make writing docs easier for SWEs
• Treat documentation like code
  • Source control
  • Follow internal rules
  • Clear ownership
  • Track issues and bugs
  • Evaluated from time to time
• Know your audience
  • Criteria: Experience level, Domain knowledge, Purpose, Seekers (Consistency) vs. Stumblers (Clarity), Customer vs. Provider
  • Keep documentation short and clear
  • Start with a TL;DR
• Documentation types: A document should have a singular purpose and do it well (SRP!)
  • Reference docs: Documents usage of code (API comments vs. Implementation comments)
    • File comments
    • Class comments: Purpose, Important methods
    • Function comments
      • Start with declarative verb for consistency
      • Google uses single prose, rather than broken-up boilerplate (e.g., Returns: XYZ)
  • Design docs: Cover design goals, implementation strategies, and key design decisions with trade-offs
    • Done and reviewed before coding
  • Tutorials:
    • Best way to write a tutorial is when you first join a team
    • Each step should be what the user needs to do, rather than having a step just for the system behavior/response
  • Conceptual docs: Provides conceptual overview of APIs or systems
    • Augment reference docs
    • Emphasize clarity over accuracy/completeness
  • Landing pages:
    • Clear identified purpose with only links to other pages
• Documentation philosophy:
  • Who, what, when, where, and why: Docs usually answer "how"; try to address the rest at the start
  • Beginning, middle, and end
  • A good doc is one that does it's intended job, rather than trying to be complete, accurate, and clear all at the same time
  • Deprecate docs that are obsolete or abandoned

Reflection:
TEAMMATES has a huge documentation guide for incoming developers. My most recent experience with the docs is helping incoming CS3281 students trying to set up the project for the first time. And my first impression of re-visiting the set up guide was how long and dense it was. However, when everyone ran into miscellaneous issues, we frantically searched through the docs for answers. And I realized that all the answers were there, just that we missed it on our first read. I think this shows the trade-off between completeness and clarity.