How to keep records so that no one understands anything. A bit of theory and harmful advice from MTS Digital
What is the problem?
Before we move on to practical advice, let's discuss what two extremes are usually encountered when implementing projects, what documentation is in general, how it is compiled and what it has to do with it Agile User Story.
No documentation at all vs too much documentation
It turns out that maintaining the golden mean is not so easy. When implementing projects, two situations often occur:
There is no documentation at all. The solution is described, for example, in tasks. There is no systematized information for users and developers. If you need to look at something and clarify it, there is simply nowhere to do it.
There is too much documentation: every little detail is documented. And when the owner of this knowledge — for example, an analyst — moves on to another project, the remaining team members are simply lost. They themselves cannot figure it out and understand which documentation relates to the product, and which to the archive part. This is also a problem for immersing new team members: it is very difficult to understand how the system works and start solving problems.
Let's note right away: in this article we write about “product” and “project” as synonyms. Both of them need documentation. Of course, there is a difference between them, but we will not dwell on it now.
Now let's get back to the reason for the two situations described. In agile development methodologies, not enough attention and time is given to quality documentation. There are no defined stages in the development life cycle, and it is acceptable to describe requirements right in the tasks. After a couple of months of work in this format, it will be very difficult to find a description of solutions and reduce them to new requirements. Therefore, the situation needs to be corrected. How – we will tell you further, but first let's define what documentation is and what it refers to.
What is documentation and how is it compiled?
First of all, documentation is business and functional requirements. Everything that concerns the description of the system functions, its integrations, methods, the relationship between the Front and Back parts, test cases. This also includes user documentation.
The documentation begins with the product owner. First, he evaluates what already exists at this point and suggests what else can be done. And only then do the technical specialists go to the second iteration and study the process more deeply.
It is best to maintain documentation for each feature and for different roles. For example, the Product Owner (PO) is interested in business requirements and what system functions implement them. System analysts, architects and developers are interested in descriptions of integrations, methods, test cases – and all this in relation to the system functions. A dedicated operations and maintenance team (if there is one on the project) needs transparent documentation so that at any time it is possible to find a specific section and study everything related to the functionality of a specific application.
The product owner and analysts must be aware of the current information. They are usually the ones to clarify what has already been documented and what is yet to be recorded and implemented.
To maintain good documentation, you need User Stories
We have already written above that the lack of attention to conscious documentation of requirements in agile development methodologies is the beginning of the problem. And now we will suggest you take a good practice from this methodology, namely User Story.
A User Story is a way of articulating a user need in the format: “As a user of a system, I want Y, so that Z.” Example: “As a user of a system, I want to be able to open an e-book where I left off to continue reading.”
We propose to use User Story as a single code for the entire entity throughout the entire development cycle – from formulating requirements for the architectural solution and setting the development task to the development itself, testing and creating user documentation. Then the requirements for the entire cycle will be linked.
Such wording at the top of the page allows you to quickly understand what system functions will be discussed below. This will help both an employee who is already well immersed in the product and a colleague from a related team who is just starting to get acquainted with it to navigate the documentation. Organizing requirements by user stories will also be useful if the product owner changes.
To clearly formulate requirements, it is useful to create templates. For example, the structure could be as follows:
general description of the solution;
target;
functionality;
Story Map;
parties concerned;
acceptance criteria.
Then, each functional capability can be detailed on separate pages. In the long term, a single format of requirements for the company can be created with links to User Story codes and tags, which will allow the requirements to be combined into one system. This system should be understandable to everyone who gets acquainted with it and works with it.
That's all for now with the theory. Now – to practice!
Five Bad Tips on How to Keep Documentation
Tip #1: Discuss the process verbally – don’t waste time writing down tasks
Get your team together at a round table and distribute tasks among yourselves. There is no need to record anything, because you have already agreed on everything personally. Just do not waste each other's time.
What is it really?
Pavel Orlov: “How it happens in reality can be explained using my example. I got into one of the projects at a stage when there was little documentation. To save resources and time, the team discussed everything verbally at a round table. It is important to note that at this stage, tasks were not formed – this was done later. Then came the stage of process setup. And when the tasks for the developer began to be collected in the backlog, it became clear that documentation had to be maintained immediately. Without it, specialists could not quickly pick up tasks, they had to distract colleagues and ask questions like: “Remind me, what did I need to do here?”
How is it in MTS?
When a product is just emerging, we quickly collect ideas, discuss them, and formulate hypotheses. And even at this stage, we already maintain documentation — at least minimally. For example, we add a short description in the User Story format. If we don’t do this, then later, at the editing stage, we will have to spend time re-learning the functionality of the product.
Tip #2: Don't open access to documentation or allow editing – in case they screw it up
Only the product owner should have access to the documentation! And if someone needs to make changes, let them write to him directly or record everything in Word on their personal computer.
What is it really?
Team members do not always work with documentation at the same time. For example, QA conducts testing after the developer has finished implementing a feature, so he will open the documentation later. A support specialist will turn to the documentation when he needs to resolve an incident – that is, much later than the developer and tester. Business can also ask the question, “Do we even have this functionality or did I not even announce it?” and turn to the documentation. Therefore, each team member should have access.
How is it in MTS?
We have access to the documentation at any time. In addition, the team can independently make changes to the documentation. For example, the analyst is responsible for filling the sections related to requirements and functionality, and the architect is responsible for the architectural part of the system. The developer can specify technical implementation details if necessary, and the tester can write test scenarios.
Tip #3: Documentation should be the same for all employees
All team members should maintain the same documentation. It is not necessary to divide it into roles – it takes a long time. It is better to collect all the data in one place.
What is it really?
Imagine a situation: someone asks the PO what functionality the product has. At this point, the PO needs to quickly navigate the documentation, while at the stage of integrating the product with external systems, he does not need to know the detailed technical implementation. Much more important for him is the description of the feature from a business point of view: “We have feature X, it helps solve issues Y.” And after the decision to integrate is made, technical specialists will join in. They will work with more detailed documentation.
So the documentation should be divided into the roles that are present in the product: business, technical roles, support, maintenance, and so on. And there should also be connecting links between them. For example, this is necessary so that when reading the documentation, a technical specialist can always go and see what the business feature and business value are. Or, on the contrary, at the top level, get acquainted with the goals and boundaries of the solution, and then with the technical details and implementation.
How is it in MTS?
Mansur Safiullin: “We have a separate section of documentation for business. It is divided into features that need to be implemented or that have already been implemented. Then the system analyst describes where and what improvements are needed for these features, and places links to development pages.
We also have a separate section for backend development. It is divided into microservices, each of which is responsible for its own part. Then each of them is divided into subsections: database structure, http methods, in each http method – a description of parameters, and so on. The same for frontend development, technical support. And of course, we have instructions for users.”
Tip #4: Don't set readiness statuses for documents, work, and tasks
Putting statuses in documentation is a waste of time. There are boards for this – for example, Jira. There you can see the statuses of all tasks.
What is it really?
It is important for team members to clearly understand what functionality is in development, what is in testing, what is already in production, and who can use the finished capabilities. A Jira board is not enough: it contains a general description of the solution. The team needs a detailed description of the functionality and readiness status – Confluence is more suitable for this.
It is especially important to update statuses for a mature product. It has many implemented features and plans for improvement, which may concern completely different parts of the product. If the documentation is not updated, it will be unclear what has already been implemented and what is yet to be developed. Because of this, some features can simply be forgotten – and never implemented. The opposite scenario: do double the work and work on a feature that has existed for a long time.
If you don't update the documentation, it will be difficult for new team members to understand what's what. It will take them longer to get up to speed.
You can work with documentation in the same way as with technical debt. For example, set aside time once a week for updating, go through the list of features that were in development, and update the description of the implemented functionality.
How is it in MTS?
In our team we use two convenient control points:
DoR (Definition of Ready) — criteria that must be met by a team in order for the task to be taken into work;
DoD (Definition of Done) – criteria after which we consider the task to be completed.
Here's an example of the criteria we use for all backlog stories.
DoR:
the story is clearly articulated;
the criteria for accepting a story are defined;
The delivery team has rated the story;
The scrum team took into account the results and artifacts of the user experience research;
performance criteria are defined;
the person responsible for accepting the history has been identified;
The team can demonstrate the story.
DoD:
the story meets the acceptance criteria and the PO accepts it;
quality gates passed;
product and technical documentation has been updated;
regression scope updated according to regulations;
there are no defects of priority higher than Minor.
In addition to DoR and DoD, we use statuses on pages in Confluence to see the degree of readiness of a document. And we link Confluence and Jira so that it is clear at what stage of development a particular functionality is currently.
Tip #5: Document your product regardless of maturity
Whether your product is in its infancy, in its maturity stage, or already mature and with legacy, documentation is always the same.
What is it really?
A nascent product does not need detailed documentation – it is important to quickly throw out ideas and move on to development. But a mature product, especially with legacy, cannot do without documentation. There can be so many features and peculiarities that it will be impossible to navigate them without a description. Now imagine that in such a situation you need to resolve incidents – you simply will not understand at what specific step something went wrong and how to fix it all.
How is it in MTS?
Our work with documentation depends on the stage the product is at. In short, it can be described as follows:
That's all for now! Well, what advice will you take into practice first? 😉
But seriously, have you ever encountered inconvenient documentation? Have you managed to defeat this monster?
