Most Software Developers dislike documenting things. But there is no denying the importance of documentation. Knowing what, how, and when to document things not only makes you a better developer, it also makes life easier for the people you work with.
It's 4pm and the Product Owner has called a meeting about a brand new project. It entails enhancing some of the core functionality of a system that has been around for years. The Product Owner is enthusiastic about all the fantastic ideas he has come up with and how it will make the lives of the system's users much easier.
You, one of the Software Developers, try to keep up with the list of features / demands / wishes being put forth. By the end of the meeting, you remember around 35% of what was said. The Product Owner then looks around the room and asks "How long do you think it will take to implement all this? Just a rough estimate.."
You could say: "4 weeks"
Or you could say: "I cannot tell until I have analysed all the requirements. Do you have a spec written down for this?"
The first response, "4 weeks", would no doubt be taken as a promise even though the Product Owner asked for a "rough estimate". It could then turn out, after you have analysed the requirements, that it in fact would take 12 weeks. Telling the Product Owner that your estimate has changed from 4 weeks to 12 weeks is sure to result in disappointment.
Therefore the second response is the wise one. Ensuring that the requirements are documented gives you a chance to analyse and clarify them before you give an estimate / promise / cast-iron guarantee.
This illustrates the importance of documentation even before a line of code has been written. The importance of documentation continues throughout the Software Development Lifecycle and greatly enhances the long-term maintainability of Software.
Documentation Before Coding
In a typical Software Development lifecycle, the requirements are established; then they are refined as the solution is implemented in parts. This, in essence, is the Agile way of doing things.
Requirements are never static. They change with time. Therefore, a requirements specification document is not static either. In fact, you don't necessarily need to have such a document. You may simply have a number of user stories that specify what is required. These user stories can be discussed and refined / rewritten if necessary. Ideally, each user story should have Acceptance Criteria that specify the expected behaviour in more detail.
Once a user story has been implemented, this would normally be demonstrated to the Product Owner or Customer. If they feel that some tweaks need to be made, then a new user story can be created to specify the changes and this can be implemented in the next development cycle. In this way, the requirements can evolve and can be documented along the way.
If the work to be implemented is of a significant size, it is sometimes useful to produce a Technical Specification that details the overall architecture / design of the solution in technical terms. This will ensure that there is a clear direction as to how to implement the solution and will ensure a consistent approach if a medium to large team of developers are working on delivering the solution. This too can evolve over time if more efficient / pragmatic ways of implementing the solution come to light at a later point.
Documentation During Coding
When implementing a solution, a developer may choose to create reference documentation that provide implementation details. This is akin to a Technical Specification mentioned in the previous section albeit for a smaller piece of work rather than the overall solution or bigger picture. Such documentation would only be necessary if the piece of work is particularly complicated and reading the code alone would not be enough for other developers to be able to maintain it.
Another kind of documentation during coding is the writing of comments in code. There is constant debate over how and when comments should be written in code and whether they should be written at all. My personal opinion on this is that comments should only be written to complement the code (i.e.) to explain why something is being done in a certain way. The how should be clear from the code itself. Advocates of clean code would be familiar with this idea.
Documentation After Coding
Once a solution has been implemented, certain documentation may need to be produced depending on the work done. For example, if it is a customer-facing solution with a user interface, then a User Guide may need to be produced or updated to instruct users how to use the system.
Reference documentation or Technical Guides can be produced if the solution is a public API or library. For example, Swagger is a tool that lets you create documentation for a public REST service. This enables consumers of the service to use it correctly. Such documentation can be produced during the coding process as well.
Common Problems with Documentation and How To Overcome Them
Drift:
Software is rarely stagnant. New features get added, enhancements are made, some features may become obsolete. This means that software documentation is also rarely stagnant. It is alive and needs to evolve along with the software that it is documenting. If it is not, then it is drifting away from its purpose of accurately documenting the software.
Such drift can be avoided by ensuring that documentation is updated whenever a change to the software is made. One approach to this in Agile is to have a definition of done which should include documentation of the change. The new feature or enhancement cannot be considered as complete unless the associated documentation has been created or updated.
Inconsistency:
Sometimes documentation is written by various individuals within a team or organisation. This can result in inconsistencies in terminology or document format, which can cause confusion.
Inconsistencies in terminology can be avoided by using an approved glossary and referring to terms in the glossary rather than using own terms. Inconsistencies in format can be avoided by using document templates and ensuring new documents are only created from approved templates. It should be clear where to find relevant documentation. Documents should be indexed and easily searchable.
No Ownership:
The aforementioned problems with documentation can also occur because documentation and the act of producing it is not officially 'owned' by anyone. This is especially true if there is absence of a culture which encourages it. If Product Owners are not required to produce requirements specifications or if programmers are not required to produce technical documentation, it will most likely be the case that they are either not produced, or if they are, they suffer from drift and inconsistencies.
It is therefore imperative that a culture of documentation is imbibed across the various functions. This will ensure that there is clarity of what is expected at each stage of the software development cycle. Developers should expect clear requirements from Product Owners, and should also expect clear technical documentation from other developers. End Users should expect clear User Guides. Such a culture would ensure a watertight space that ensures that documentation is not only produced when required but is also maintained throughout the life of the software system.
Conclusion
Creating and maintaining clear, easy-to-locate, accurate documentation will reduce the cost of developing and maintaining software in the long-run. Therefore, every organisation or team should have a strategy to ensure that this is being done as a core activity.