The Importance of Documentation – When, Why, and How to Write

When it comes to documentation, numerous questions arise:

Is it necessary to write documentation?

Can we forgo it altogether?

If we can skip it, in which cases?

When is it necessary to write documentation?

What are the different types of documentation?

And so on.

In general, documentation should always be written, but there are instances where it can be omitted.

Let's begin by discussing a specific type of documentation known as a project specification.

A project specification is an essential document that must always be written. It is mandatory as development cannot proceed without it.

Every project, regardless of its size, requires a specification. This ensures that developers and business analysts are on the same page, resulting in the desired product and avoiding any misunderstandings.

Even in startups, where requirements may frequently change, including in the case of a Minimum Viable Product (MVP), starting with a specification is crucial to understand what we are developing and the expected outcomes.

What if the requirements change during development?

In such cases, the specification should be updated. All changes need to be reflected in the specification document.

Later on, this specification will serve as the foundation for the documentation.

How does documentation differ from a specification?

Documentation describes how things work, providing an overview of the system's functionality.

On the other hand, a specification defines the desired behavior, outlining the expected outcomes and requirements.

Ideally, both should align perfectly. However, in practice, it is not always possible to achieve the exact desired outcome, and compromises may need to be made (often to avoid excessive time investment in pursuit of the perfect solution). The specification tends to provide more detailed descriptions of the business logic, while documentation focuses on the technical aspects of the solution.

What are the different types of documentation?

1. Requirements Documentation: This type of documentation captures the functional and non-functional requirements of a software project. It outlines the goals, user stories, use cases, and acceptance criteria, providing a clear understanding of what the software should achieve.
2. Design Documentation: Design documentation focuses on describing the high-level and low-level design aspects of the software system. It includes architectural diagrams, system flowcharts, database schemas, interface designs, and other design artifacts. This documentation helps developers and stakeholders visualize the structure and behavior of the system.
3. API Documentation: When developing software with exposed APIs (Application Programming Interfaces), API documentation becomes crucial. It explains how to interact with the APIs, including details about endpoints, request/response formats, parameters, and authentication requirements. Clear API documentation enables developers to effectively integrate the software into their applications.
4. Installation and Deployment Documentation: This documentation guides users or system administrators on how to install, configure, and deploy the software system. It includes step-by-step instructions, system requirements, dependencies, and troubleshooting guidelines to ensure successful installation and setup.
5. User Documentation: User documentation focuses on providing instructions and guidance for end-users of the software. It includes user manuals, guides, tutorials, FAQs, and other resources that help users understand and utilize the software effectively. User documentation is essential for improving user adoption and reducing support requests.
6. Testing and Quality Assurance Documentation: This documentation captures the test plans, test cases, test scenarios, and test results for the software. It outlines the strategies and procedures for validating the software's functionality, performance, security, and other quality attributes. Testing documentation ensures thorough testing coverage and aids in identifying and resolving defects.
7. Maintenance and Support Documentation: This documentation assists developers and support teams in maintaining and troubleshooting the software system. It includes knowledge base articles, debugging guides, known issues, and workarounds. Maintenance and support documentation help ensure effective system maintenance and prompt issue resolution.
8. Change and Release Documentation: Change and release documentation tracks the changes made to the software system over time. It includes release notes, version histories, change logs, and upgrade instructions. This documentation helps stakeholders understand the evolution of the software and plan for upgrades or migrations.

Should documentation always be written?

Ideally, it is best to always write documentation. It is never unnecessary. In some cases, it is necessary to write documentation, while in others, it can be delayed slightly.

By postponing the writing of technical documentation, we accumulate technical debt that will eventually require attention. And the longer we delay, the more challenging it becomes later on. Therefore, I would recommend dedicating periodic time to address technical debt in general, including documentation writing, to avoid a situation where a significant amount of time is needed, leaving the project without updates in terms of new features.

In which cases can documentation writing be postponed?

1. Simple Projects: For small, straightforward projects with minimal complexity, documentation can be kept to a minimum. If the codebase is self-explanatory, well-structured, and easily maintainable, the need for detailed documentation may be reduced.
2. Prototyping and Proof of Concepts: When creating prototypes or proof of concepts, the focus is primarily on quickly validating an idea or concept. In such cases, documentation can be limited to capturing the core principles and insights rather than exhaustive technical details.
3. Rapidly Evolving Projects: In dynamic development environments where code and requirements are rapidly changing, spending excessive time on documentation may hinder progress. Instead, emphasizing code readability, maintainability, and inline comments can be more effective in keeping track of changes.
4. Personal Projects or Small Teams: In cases where the project is solely developed by a single developer or within a small, tightly-knit team, the need for extensive formal documentation may be reduced. Here, clear communication and shared understanding among team members can compensate for the lack of comprehensive documentation.

In which cases is it absolutely necessary to write documentation?

In all other cases :)

1. Complex Systems: Projects that involve complex architectures, intricate algorithms, or intricate integrations often require comprehensive technical documentation. It helps developers and stakeholders understand the system's design, behavior, and dependencies, facilitating maintenance, troubleshooting, and future enhancements.
2. Larger/Growing Teams: When multiple developers are involved in a project, well-documented code and accompanying technical documentation are crucial. It ensures that team members can easily understand and work with each other's code, reducing the learning curve and enabling effective collaboration.
3. Long-Term Maintenance: Software projects have a lifecycle that extends beyond the initial development phase. Documentation becomes crucial for future developers who may need to maintain or enhance the system. It provides insights into the codebase, design decisions, and implementation details, making it easier to identify and address issues down the line.
4. Compliance and Regulations: Certain industries, such as healthcare, finance, or government, have strict regulatory requirements. Technical documentation becomes necessary to demonstrate compliance with regulations, security standards, privacy policies, or quality assurance measures.
5. Reusability and APIs: When developing reusable components, libraries, or APIs, clear documentation becomes vital. It helps other developers understand how to use the code, its capabilities, limitations, and integration requirements. Well-documented APIs are particularly crucial to enable seamless integration and foster developer adoption.
6. Dealing with Technical Debt and Refactoring: It is crucial to document things while refactoring a large system. Documentation helps keep things organized and well-structured.

How not to write documentation?

You should avoid simply listing the names of modules/functions and providing explanations that are redundant with the function name itself. For example, saying "Register user function. It registers a user" adds no value. Writing documentation just for the sake of it is pointless. Documentation should always serve a specific purpose.

How to write documentation correctly?

First, understand the purpose of the documentation. Based on its goal, write it accordingly. If it's an instruction, structure it as step-by-step procedures. If it's an API description, provide examples of usage, including input parameters and expected output.

Second, write in a clear and straightforward manner. Use simple expressions and short paragraphs. Avoid including unnecessary information in the documentation, but make sure it contains all the necessary details.

Always keep in mind that the primary objective of documentation is to provide support. Put yourself in the shoes of someone encountering the system for the first time and asking questions. Try to answer those questions in a simple and understandable way, avoiding project-specific terms or providing explanations for them.

Documenting a feature should be an integral part of the development process, just like testing. A feature should not be considered complete until its documentation is written.

Therefore, when planning, allocate the necessary time for documentation writing within the development timeline.

In summary:

• Project specification is always a must-have, and specifications for complex features are also essential.
• For small projects, documentation may be optional in the beginning.
• As the project grows and becomes more complex, documentation becomes necessary.
• Documentation should not be written just for the sake of it, but with a specific purpose in mind. The type of documentation may differ depending on the purpose.

---

originally posted on linkedin.com