In the world of software development, documentation has always been a topic of debate. Some argue that it is essential for the development process, while others believe that it is a waste of time and resources. With the rise of agile methodologies, this debate has only become more intense. So, is documentation really necessary in the software development process?
Balancing Working Software with Essential Documentation
Software development in Agile methodologies is often associated with the lack of project documentation as limiting the agility and flexibility of the team. This popular misconception stems from a misunderstanding of the most basic Agile principles, the Agile Manifesto. After all, one of the four principles is "Working Software over Comprehensive Documentation," which actually prioritizes work over documentation. But does this completely detract from the importance of documentation? Absolutely not! Often overlooked in the interpretation of the manifesto is the addition under the principles: "That is, while there is value in the items on the right, we value the items on the left more." clearly indicating the value of the classical approach to development with the creation of documentation.
What Documentation Can Be Created?
Let's define what we mean by documentation. In the context of software development, documentation refers to any written or visual material that describes the design, functionality, use of a software system and/or processes.
The main two categories are product and process documentation. While both types of documentation are important, they serve different purposes and are created at different stages of the development process.
Process Documentation
Process documentation refers to documentation that describes the processes and procedures used to develop and maintain software. It is used to ensure that everyone involved in the development process understands how tasks are to be completed and how quality is to be ensured.
Process documentation can include things like:
coding standards,
testing procedures,
version control policies,
code review guidelines,
timelines,
resources,
risks involved,
project plans,
schedules,
budgets,
status reports,
risk management plans.
Product documentation, on the other hand, refers to documentation that is created for the software product itself. It can be further divided into documentation for final users and system documentation.
Product Documentation
User documentation is used to help users understand how to install, configure, and use the software. It can include things like user manuals and installation guides.
System documentation serves the purpose of helping developers understand how the software is designed and built. It usually consists of the requirements document, design, architecture, source code, technical specifications, testing guidelines, API documentation and maintenance guide. Of this list, one of the most downplayed documents is the requirements document as something that “can be decided later on”. This approach generates a lot of problems in project work and is the basis for many iterations of amendments. Therefore, at Primotly we pay very great attention precisely to the documentation created at the very beginning of cooperation.
How Do We Approach this at Primotly?
Product documentation
We follow Scrum principles in our work, adapting them to our needs. We are flexible to the needs of each client, maintaining basic procedures to streamline processes.
An important step in building products with us is the initial workshop, where we gather the knowledge base for the initial project documentation. At this stage we gather such information as:
- the client's general business
- short- and long-term business goals
- functional requirements
- non-functional requirements, such as hardware or technology requirements
- planned external integrations
- possible time constraints
- use cases for different entities
- UX and UI needs.
Based on the workshop, a first version of the documentation needed to estimate the time to work on the project is created. Sometimes this first version is already the final basis for design work, and if the client needs to rethink some parts, it is supplemented at subsequent workshops.
Although the basic elements are the same for each client, the initial documentation often differs in the table of contents and number of pages. This is due to the complexity of the project, which may require specifying additional requirements already at this stage - for example, the type of reports generated or forms needed.
Each client will find the following information in its documentation:
- A brief description of the client, its business, market and target group
- Business objectives of the project
- A list of functional requirements supported, if necessary, by relevant supplementary material, such as use cases or BPMN diagrams
- A list of external integrations, for example with programs currently in use
- A list of non-functional requirements.
Such a collection of information is a good basis for time and cost estimation and planning of project work.
As for the other parts of system documentation - we use advanced tools such as Stoplight and GitHub to create documentation on the fly, which optimizes the time spent vs. the effect ratio.
Process documentation
Do not expect from working with us a multi-volume book with incomprehensible descriptions of processes and procedures. In our work, the priority is good communication, and such a document would definitely not improve it.
Instead, we use dedicated solutions that are confirmed with the client and allow for easy workflow. Jira or Linear allow us to easily present plans or estimates, Confluence and Miro are used to help with roadmapping, and we keep meeting notes on a shared drive so that no project knowledge is lost. It is important to note that the level of detail included in each type of documentation will vary depending on the needs of the project and the specific client. We believe that agile methodologies recognize the importance of documentation, but emphasize that it should be done in a lightweight and flexible manner.
Documentation in the Software Development Process
While documentation is not the focus of an agile approach to software development, it is still necessary. The key is to have an adaptable and streamlined approach, and to use documentation as a tool for communication and collaboration. By doing so, teams can ensure that they are building the right software, in a way that is efficient and effective.
