Documentation
Overview
This blog post discusses the Documentation chapter in the Software Engineering at Google book. The chapter looks into the importance of documentation in order to ensure that ideas in code are communicated efficiently. Let’s dive into the chapter and see what constructive tips we can take away from it so that we can improve the work of our engineering team!
Summary
This section of Software Engineering at Google book deals with the importance of documentation and how it makes the use and maintenance of code much easier when you can read about the processes that a codebase takes. Documentation in this sense is not just about how the code is run, but all of the work put into the code to make it readable such as descriptive notes and tutorials. Good documentation makes code more comprehensible and allows for quicker transitions for new developers working on the project. This not only gives your project a cleaner look but also allows for fewer questions and confusion which could save a lot of time down the road. One of the main problem with documentation, however, is that the benefits of writing it are not immediately evident and it may be time-consuming to make. This causes a lot of developers to write it off or delay it, then when other developers need to understand this code there is nothing to help them. However, the writing of documentation is vital to a project’s long-term success for users to understand changes and features in code.
This article explains that we should treat documentation the same way as we treat code. This means that documentation must be maintained, have a consistent style, and should avoid grammar errors. Software engineers should periodically review and test their documentation to make sure that it is accurate and follows the current goals of the tool. To do this each section of documentation needs an owner or a group of owners who are responsible for creating documentation for commands. These groups would be responsible for their sections of code to be clear and maintained, allowing for long-term maintenance of each section of this documentation.
Another point to consider when writing documentation is to know for whom you are writing your documentation. Since often writers of documentation write it only with their own goals in mind, here are some questions that the should consider when documenting source code:
- Are you writing for someone with many years of development experience or only a few weeks?
- Are you writing for a developer on your team or the general public?
- What information do your users need to know first and what last?
All of these questions need to be considered when creating documentation to make this writing as useful as possible to your users as documentation that is too complicated could confuse people outside of your team if you are not specific enough.
The type of documentation style you use is also something that needs to be considered as different types of notes can help with different internal issues. Reference documentation is one of the most important versions of documentation as it references direct code sources in code segments. File, class, and function comments are some of the most common that help us explicitly state what different sections of code do. Design documents are another type of documentation that enforces design choices made for different projects, these documents are made before projects are started so that code can be standardized in the entire project. In-depth tutorials are also very helpful as they can explain exactly how processes are run which can help new users get up to running quickly. Conceptual documentation is high-level documentation that gives less in-depth information as it is an issue that is more complicated than reference documentation. These documents cover processes that cannot be lowered down to specific sections of code but rather a larger, more theoretical process. Finally, landing pages are good documents to make to ensure that developers going to your documents for the first time have a guide on where they should go to best fix their issues.
Ultimately, the creation of documentation is a team-based endeavor that requires a lot of effort to set up but is worth it in the long run. Good documentation should have a clear intended audience while also trying to balance accuracy and completeness so that it is as helpful as possible for the intended audience. Software engineers must maintain and update documentation so that it stays up to date as new features are added, thereby ensuring that all features of a software tool will be understood by its audience.
Reflection
The chapter on Code Documentation provides us with important information on how documentation is important, despite the fact that some engineers consider it “downstream” or unimportant. Nonetheless, despite its appearance of unimportance due to its lack of immediate benefits, the article shows us how documentation is an extremely important aspect of programming and software engineering by explaining how it promotes education among software teams as to what the code does and answering questions about its effectiveness, as well as increasing professionalism and allowing the formulation of project plans.
Action Items
We should establish a universal outline or format for documenting code that ensures consistency across both projects, making it easier for team members to navigate and understand the code. Since different team members might contribute in various ways or focus on different aspects of the code, having a flexible yet standardized documentation format allows for a cohesive and comprehensive overview. Doing this ensures that our code will be more accessible to people working on the tool now and people who will work on it in the future.