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
< BACK NEXT >
Tweet


   


   

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