Technical documentation in software engineering is the umbrella term that encompasses all written documents and materials dealing with software product development. All software development products, whether created by a small team or a large corporation, require some related documentation. It is inescapable for any process or product that will need any length of operation time and support to survive.
As one of the Agile Manifesto values suggests, putting – “working software over comprehensive documentation -“, the idea is to produce documentation with information that is essential to move forward when it makes the most sense. This is where most teams get into the murky depths of what makes the most sense, how early to create it and how often to maintain it.
As a developer, and as a team, you will have to determine what is appropriate for your own projects, however, I believe that developing a consistent habit to address this skill that most developers leave till the end is in fact essential to your success.
Importance of Documentation
Different types of documents are created through the whole software development lifecycle (SDLC) which exists to explain product capabilities, unify project-related information, and allow for discussing all significant questions arising between stakeholders and developers. The first challenge that teams typically face is that they are all looking at the challenges through their own filters, getting on the same page at the beginning of a project will pay dividends in the long run.
“Produce documentation with information that is essential to move forward, when it makes the most sense”
This does not mean that documentation is less important, but the opposite, each change, decision, and pivot point can affect the outcome of the product and should be documented so that during maintenance cycles teams will not be covering the same ground again and again.
It is important to note that the graphic does not represent the amount of documentation produced through the life-cycle of the project, just the level of effort to achieve the same result. Building the documentation as you build the product makes those living documents more relevant and reliable over the full course of the development and support activity.
If anything Agile produces more documentation by the end of the project than many waterfall-based projects. Agile also provides a lower threshold of starting documentation to get moving on producing working software.
Products can be measured in their maturity by the team’s documentation practices. Take for example any of the open source libraries and vendor products that you use on a regular basis today, if their documentation was sparse, you would start looking for something that had more details because it would imply that the product does not have a significant level of support or versatility for whatever use you are trying to put it to.
The main goal of effective documentation is to ensure that developers and stakeholders are headed in the same direction to accomplish the objectives of the Project.
Types of Documentation
It is important to understand what types of documentation are the most impactful for your team and you as an individual to focus your efforts on at any point during development. Most product documentation helps the team and users to be on the same page, whereas process documentation helps to keep everything in line and on track for delivery and long-term usage. Below are some additional descriptions to help you classify the different documents you may need.
Product Documentation
Describes the product being developed and provides instructions on how to perform various tasks with it. In general, product documentation includes requirements, tech specifications, business logic, and manuals. There are two main types of product documentation:
System Documentation
Represents documents that describe the system itself and its parts. It includes requirements documents, design decisions, architecture descriptions, program source code, and FAQs.
User Documentation
Covers manuals that are mainly prepared for end-users of the product and system administrators. User documentation includes tutorials, user guides, troubleshooting manuals, installation, and reference manuals.
Process Documentation
Represents all documents produced during development and maintenance that describe… well, the process. The common examples of process-related documents are standards, and project documentation, such as project plans, test schedules, reports, meeting notes, or even business correspondence.
The main difference between process and product documentation is that the first one record the process of development and the second one describes the product that is being developed.
The Who, What, When, and Where of Documentation
Write just enough documentation
You should find a balance between no documentation and excessive documentation. Poor documentation causes many errors and reduces efficiency in every phase of software product development. At the same time, there is no need to provide an abundance of documentation and to repeat information in several papers. Only the most necessary and relevant information should be documented. Finding the right balance also entails analyzing the project’s complexity before development starts.
Documentation is an ongoing process
This means that you should keep your documentation up-to-date. It is very important as documents that aren’t current automatically lose their value. If requirements change during software development, you need to ensure that there’s a systematic documentation update process that includes information that has changed. You can use automatic version control to manage this process more efficiently.
Documentation is the collaborative effort of all team members
The agile method is based on a collaborative approach to creating documentation. If you want to achieve efficiency, interview programmers and testers about the functionalities of the software. Then, after you have written some documentation, share it with your team and get feedback. To get more information try to comment, ask questions, and encourage others to share their thoughts and ideas. Every team member can make a valuable contribution to the documents you produce.
Use cross-links
Use cross-links between documents, whether those are product pages or user guides. Proper navigation through your documentation is important to give the reader the right understanding of a subject. Such practice can be considered user-flow, but for your project documentation.
Don’t ignore glossaries
Documentation can be dedicated to internal or external usage. In the case of external documents, it is better to clearly explain every term and its specific meaning in the project. Documentation should communicate ideas in clear language. This goes back to ensuring that the team and users are operating on the same vision of what needs to be accomplished and how to get there. Overused terminology and abstractions are one of the quickest ways to get to miscommunication when discussing nuanced effects and interactions.
Documentation exists to:
- explain product functionality
- unify project-related information
- allow for discussing all significant questions arising between stakeholders and developers
Building good documentation habits
Still with us so far, GREAT!
By now you have a grasp on the need for documentation, next is how to integrate this into my ongoing developmental skill set and daily development behavior. The best way is to make it a habitual activity that is addressed every day you write code. Small chunks of consistent effort will build your final product, just like you are doing with your Agile development processes.
Keys to building the habit
Using the lessons learned from reviewing books like the Power of Habit, Atomic Habits, and other similar books, making adjustments to the Cue->Routine->Reward cycles to include this activity into my coding behaviors. Before starting to build a new class or function, setting up the process to adjust the documentation that is relevant first, instead of leaving it to the end is where I am planning to begin. That way I can ensure that decisions and changes in approach are adequately captured along with my code delivery instead of trying to update it after completing a significant span of coding effort.
That is the Cue and Routine, but what about the Reward? What would help to cement the cycle into forming that autonomic process that is required for the behavior to become a habit? Something to ponder on while I seek to build more useful software capabilities.