This is the sixth article in a series where we cover the book Software Engineering at Google by Titus Winters, Tom Manshreck, and Hyrum Wright. ๐ We will go over various aspects of software engineering as a process, including the importance of communication, iteration and continuous learning, well-thought-out documentation, robust testing, and many more.
Today we discuss documentation, which often goes hand in hand with working code. It comes in various forms and flavors - starting from in-code comments around implementation details, and flow diagrams, all the way to design documentation or technical requirements specification. Let's dive in!
Benefits of documentation
As usual, we'll start by outlining the benefits we gain as engineers by creating and maintaining documentation for our systems. ๐ Here are the points that the book brings up.
More comprehensible code and APIs. Writing documentation helps formulate an API. If you can't explain it in plain English, you probably haven't designed it well enough. On the other hand, if you have to add elaborate comments, there might be room to make the code more self-explanatory.
Focus on clearly stated goals and objectives. Writing high-level design documents helps you and your team narrow down on technical direction and key implementation aspects. Once the goals and objectives are clearly stated, it's easier to follow them in the code.
Easier to follow manual processes. Having documentation will prompt fewer questions from other users around processes - especially those processes that can't be automated. If you have to explain something to someone more than once, it usually makes sense to document that process.
Smoother onboarding for new members. Writing documentation provides a road map for maintenance and a historical record, that's especially useful for new members, unfamiliar with the code. Good comments help out a great deal when you're staring at code, trying to figure out what it does or what's wrong.
Documentation done right
We established that there are clear benefits that come from writing documentation. Next, the book gives out some guidelines on how to make the documentation most effective. ๐
Identify the audience your document needs to satisfy. A design document might need to persuade decision-makers. A tutorial might need to provide explicit instructions to someone unfamiliar with your code base. An API might need to provide information for any users of that API. Who the target audience of the document is should affect how you structure and write your document.
A document should have a singular purpose and stick to it. Just as an API should do one thing, avoid trying to do several things within one document. Instead, break out those pieces more logically.
Share the document at the lowest applicable level. Creating and maintaining centralized sources of information is expensive and not all content needs to be shared at an organizational level. When deciding on how much to invest in a resource consider your audience. Who benefits from this information? You? Your team? All engineers? Target your document appropriately.
Conclusion
That's it for today. Documentation is often so tightly coupled to code that it should, as much as possible, be with the same level of care and attention as code. Here's a short summary of things we went through:
documentation encourages more comprehensible code and allows to focus on goals and objectives
documentation makes it easier to follow processes and serves as a historical log for new and current team members
make sure your documentation is tailored to and shared with the right audience
stick to a single purpose for any piece of documentation
Next, we will discuss a particular type of code that all applications should contain - automated tests. See you! ๐
If you liked the article or you have a question, feel free to reach out to me on Twitterโ or add a comment below!
Further reading and references
The original Twitter thread with notes from the book.
Link to purchasing the book.
Photo by Tarang Dave on Unsplash.