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

  • Use the same policies for documentation as you use for code (lives in source control, changes are reviewed, measured for accuracy (tests), etc)
  • Google moved from HTML / CSS documentation to Markdown. Markdown is much easier thus software engineers documented more readily
  • Know your audience, write for your audience
  • 3 criteria for to take into consideration when determining your audience:
    • Domain knowledge (which domains will the reader know about)
    • Experience level of the reader (senior vs junior)
    • Purpose (what admins need to know about the backend vs what users need to know about the frontend)
  • Keep your documents short. Enough so that a junior can read it but not detailed enough that it annoys a senior
  • Consider how the consumer of the document will find it (2 ways)
    • Stumblers - The key is clarity, not sure what they want so use summaries and TLDRs so they do not have to read the entire document
    • Seekers - The key is consistency, keep things consistent so they are easy to consume
  • Design Documents:
    • Consider templates to create consistency (eg: to remember to integrate security early on as part of each design)
    • Should cover the goals, implementation strategy, and explain tradeoffs
  • Code comments have two types: API comments and implementation / design comments
  • You can use existing frameworks to create documentation based on code comments (PyDoc, GoDoc, Javadoc)
  • File comments - Each file should have a summary at the top
  • Class comments - What’s the purpose of the class?
  • Function comments - What the function does
  • Conceptual documentation is higher level documents such as a document that describes the lifecycle of user data within a system
  • Tutorials:
    • Helps people get up to speed quickly
    • Number each step (not bullets, numbers)
    • Only document the steps the user has to take, not things that happen in the background as a part of the process (eg: “wait for the login process to complete” isn’t a good step)
  • Landing pages should only link to other page and is not itself considered documentation



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