Documentation

Programming is fun, analyzing problems is fun, designing systems is fun, but documenting is boring. Creating documentation is generally considered a necessary evil, which is why teams usually postpone it to the uttermost possible time, and very often indefinitely. As a result, it often does not happen at all. Besides, with the increasing popularity of agile methodologies that proclaim "Working software over comprehensive documentation" (see Agile Manifesto), teams received another justification for not documenting. Not only is the statement misinterpreted as "Don't document software, source code is enough", it is also very often applied to any documentation, not just the software specifications. Both are wrong since not all important aspects of software could be found in the source code, and the need for "documentation" goes beyond the description of how systems and applications work.

So what should be documented and how the documentation should look? The term itself is quite ambiguous as there are actually several types of documentation, and its form and amount depend on from which perspective we are looking at it. In general, it is influenced mainly by "what" is the subject of the documentation and "why" it is needed.

Different parties have different opinions on "what" is the documentation as they look at it from different points of view. Development teams work mostly with the analysis, design, and architecture of the systems. Analysts document requirements, processes, or even whole parts of the organization. And business stakeholders are interested in how the business work, what processes are performed, and which guidelines the employees must follow. Obviously, documentation means different things to different parties, and as a result, there cannot be a single universal definition and also no unified form.

The other important aspect is "why" the documentation is created - its purpose. When the aim is to document a legacy system, the documentation will naturally look different from the system specification, which is going to serve as the material for development. It will differ when it comes to the type of information included, the amount of information, and it will also influence the documentation form.

Many teams also hesitate as to whether the documentation is needed at all. Mostly it is, but in various situations, it will look different. A quick single-phase project will obviously require different documentation than a big multi-phase enterprise solution. It is possible to implement a few-week-long project with only minimal documentation, but if the project takes months or even years, the information for the upcoming phases must be captured to keep the continuity of the development. We are elaborating on these considerations more in the following sections.