Your Project, Documented: Why You Should Still Care About Documentation

To Document or Not to Document?

Nowadays, with the cascade/waterfall software development method passing into history, it may seem that the huge and dusty time-worn books on project design must follow, freeing up some empty space on everyone’s bookshelves. That opinion is supported by one of the key rules of Agile (one which, as an aside, is often interpreted incorrectly):

“Working software over comprehensive documentation”

Within a modern world that moves at lightning speed, it’s easy to conclude that there’s no place and time for documentation upon the constantly beating wings of a project’s progress. To deliver “value” to businesses, we have to write code as fast as possible; otherwise, we risk falling behind in the endless war among competitors, watching helplessly as the more rapidly moving competitor moves ahead and choking on the dust coming off their wheels. Nobody wants to be left in the dust. Accordingly, they’re inclined to include things like “comprehensive documentation” in the pile of things that nobody has time for.

Unfortunately, this kind of thinking is a giant trap. The absence of documentation may look attractive in the here-and-now, but in the long term, it will be the reason for the failure of both the software you developed and your business.

There’s no doubt that Agile is pushing documentation away from a position of leading importance. However, it’s totally wrong to think there’s no place for it in the world of software development. While it may have a new position in the pecking order, its central role remains the same. It’s still critically important to document all developed solutions and describe accepted agreements. The biggest difference is that today, to achieve maximum flexibility in the process, one must create documentation not before but rather during the process of product creation.

To understand which moments must be recorded at each stage of the software development process, let’s examine the existing types of documentation.

Types of Documentation

Requirements are a language of cooperation used to facilitate clear communication between the development team and the business. Requirements are used to define what has to be done, as well as to provide a general understanding of a complete task. It’s important to document not only functional requirements but also nonfunctional ones, such as performance and fail-operational capability requirements and other nonfunctional requirements.

In the world of Agile development, requirements are usually written as user stories, and their content and completeness may change during project development. Such an approach allows for quick and easy implementation and changes during the product development process. However, to avoid getting lost and confused amidst constantly changing requirements, each and every one of them must be recorded in the project’s documentation.

Architectural documentation is used to keep track of the highest-level decisions made about the structure and the behavior of the system. During this stage, one must document how the listed requirements have to be implemented. Examples of architectural and design documentation may include wireframe diagrams, user interface sketches, topology descriptions, inspection testing plans, and even the structure of the classes. (The last category I mentioned — the structure of the classes — is used extremely rarely, due to the huge number of variations of the developed product and the existence of specific tools which can be used to generate such diagrams on the fly.)

Technical documentation captures the program code. While this type of documentation is usually hidden from the wider world, it doesn’t make it any less important. Such documentation includes API descriptions, lists of environment variables, ReadMe files, and even the comments in the code.

It’s no surprise that programmers don’t really like writing documentation; in fact, they rather hate having to document so-called self-documenting code. In fact, those aren’t just empty complaints. On one hand, various automation tools (e.g., Swagger or Javadoc) allow the generation of up-to-date documentation at any given moment in time; on the other hand, clear and well-structured code doesn’t need explanation. Since it’s easy to read and understand such code, its purpose can be easily understood. The code itself acts as the documentation.

It’s also worth noting that unit tests play a big role in the technical documentation process, too. To save precious time, people prefer to avoid using them in the face of approaching deadlines. However, unit tests will be used as code specification, making support for further changes much easier in the long term.

There’s no need to discuss the importance of the end-user documentation that takes the form of various sets of instructions, user manuals, and tutorials. But I will call out that, even in situations when a product will never be directed to an end-user and its only planned use is as a B2B solution, some thorough and detailed instructions can be really useful. Ultimately, the software is genuinely useful only when it’s used by a competent, proficient user, and a good set of instructions can help users to achieve that proficiency.

While this type of documentation is usually considered entirely separate, it still supports a specific stage within the software lifecycle. The main task of marketing documentation is to attract attention to the product (e.g., in the form of advertising), informing users of the primary advantages and proper positioning of the product relative to its competitors. We all know that advertising is the engine of commerce. Accordingly, if there’s no marketing documentation, even the most sophisticated and useful software may be extremely unpopular and face all-around failure.

Conclusion

In the modern world of software development, documentation is not something out of a lost past, and it’s definitely not a dusty old book sitting unused and unloved. Documentation remains an important and flexible tool that facilitates efficient communication in a world where virtually everything changes by the minute or even the second. So, raise your guards, troops, and ward off the mistaken thinking that documentation has no place in our modern, Agile world. Document safely and responsibly!