Software Engineering At Google
Chapter #10 - Documentation (2 of 3)
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
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
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.
© 2021 Josh Turgasen
All product names, logos, and trademarks are property of their respective owners