Software Engineering at Google Chapter #10 -Documentation (1 of 3)

  • Software engineers will always need to write documentation themselves because they are the ones with the best knowledge to do so
  • Engineers need the proper tools and incentives to write documentation
  • Treat documentation as code and make it part of the normal engineering workflow
  • Documentation enables the organization’s knowledge to scale
  • Be aware the documentation requires a great deal up upfront effort with no visible payoff, but it does payoff in the long term
  • Like code, documents are written rarely but read repeatedly
  • 4 reasons software engineers dislike writing documentation:
    • It’s viewed as an extra burden
    • Difficult due to lack of tools or workflow
    • Writing is viewed as a separate skill from engineering
    • An engineer may not feel they are a capable writer
  • Documentation provides the following 3 benefits to the engineer to writes it:
    • If you API is well documented, other developers will assume your API is well written
    • It is a roadmap for design decisions and historical context
    • Users ask fewer questions when good documentation exists
  • Writing documentation forces the engineer to explain the API and if they are unable to explain it then it should probably be redesigned or re-evaluated
  • Optimize for the reader
  • Similar to programming, documentation has rules (syntax, style guides, etc)
  • Good grammar makes wording more precise, and precision is important as to not distract or mislead the reader



Thank you for your time and attention.
Apply what you've learned here.
Enjoy it all.