As you know, Agile Manifesto claims “working software over comprehensive documentation”. So you might get the impression that Agile methodology rejects all documentation. Then you are wrong. We will provide a brief overview of the best practices of Agile documentation.
Yes, indeed static documentation is too rigid for Agile. Nevertheless, it is still necessary. Main reasons why people need the technical design document for their work:
- Stakeholders require the reports
- Customers need to feel more secure
- To keep track of everything on the project
- For audit
- As a training material for new people in the team
As you see, even Agile still needs to fulfill these points. Of course, it is done in a different way than in traditional software development scheme.
How it used to be in Waterfall (Traditional) methodology:
- Before the actual development began, all the details were gathered in a Vision Document. It was an extensive overview of the main goals and objectives and the plan how the working process was going to look like.
- A deep analysis was conducted and all the requirements were listed, business requirements and functional specifications. Separately, of course.
- All architecture and design details were thoroughly described and documented before they were implemented.
- There were a number of user documents, containing verbose explanations on how to work with the system.
- The release documents and long post-development reports. In addition, extensive support documentation.
In Agile some of these documents are needed, but the content is totally different. We present some basic rules for Agile documentation, that will help you to reduce your workload and spare you some time, money and paper waste.
Agile documentation best practices:
- Only the relevant information: Agile suggests that only the most necessary information should be documented.
What is the need for documenting something everyone knows? Create a vision, if it helps you to get fundraising. Write only the customer documents your customers require. Document your decisions only if there are alternatives and you need a reminder of what was behind those decisions.There is no need in extra documents, your time can be spent on something much more useful. Prefer executable specifications over the theoretical ideas, not grounded in reality. Try to minimize the overlapping. Do not repeat the same information in a few different papers. Oftentimes the developers are prone to do that. Your task is to avoid it. - Wait before documenting: This is the best way to avoid the false information in your papers. Document late. Wait until the decision is implemented and there’s no going back until you actually put it on paper. The information is stabilized and reliable. You economize the cost, time and effort, spent on redoing your documents.
- Get a tech writer: If you can afford it, get a special person to take care of your documentation. First, you’ll know that there will always be someone in charge. Second, it will be done properly. Developers are good in technical part, but they are way too often helpless when it comes to describing it. If you hire someone with an engineering background, you’ll kill two birds with one stone.
- Be specific: Keep in mind, that every project has its own requirements and specifics. You cannot apply the document templates for one project while working with another one. Some fields might not even exist in a project whilst some important ones are missing.In addition, the customers are different and what works with one is simply not enough for the other. Let the customers decide on the content and amount of your documentation. It will save you some extra work and nerves.
- Keep it all in one place: Technical design documents have to be accessible and transparent. You need to have them available for anyone who might be in need for them. So as not to have a mess, keep all your papers in order and in one place. A real life-hack is to create your own Wiki. How to manage that?
- Every developer is supposed to contribute to your Wiki.
- All information there should be divided into sections for your convenience.
- There has to be an editor. A senior engineer or anyone with a deep understanding of the system and strong writing skills. His responsibility is to check the contributed information, make it readable, get rid of the ballast and the overlappings.
- Regular updates should be made if any piece of information is out of date or simply is no more relevant. Wikis allow it, what cannot be said about the stringent traditional documentation samples.
- All employees should look the Wikis through from time to time. It will help them to remember your main objectives. In addition, it will keep them informed about all the renovations.
- There are links and references to your other pieces of documentation. Like this, you will always be able to find what you need.
How to deal with every particular piece of the Agile documentation?
| Vision statement | It usually contains all the main information about the project: the cost estimates, the main objectives and targets, all the benefits, the possible risks and the milestones. Create it only when it is strictly needed, like when your stakeholders require it or you need to attract investors. The best way to do it – just list the significant points. |
| Project overview | Here we have the detailed description of all the materials used, the tools and technologies, the stages of development, the staffing etc. You don’t want to include here the general knowledge, only something that needs to be put in black and white, to be pointed out. |
| Requirements document | It has to contain the business rules of your project as well as the functional requirements. It needs to be simple and clear – for all members of your team to be able to constantly revise these. |
| Product Backlog | A feature list, prioritized by the stakeholders. It should contain short descriptions of all features desired in the product. Usually, a product backlog is based on user stories. |
| Design papers | Here include the user stories and interface prototypes. Do not give too much, only those decisions which are ambiguous and need some clarification. |
| System documentation | It is an overview of your system – the project’s architecture and the technical peculiarities. |
| Support papers | It is a necessary part – the training materials for your support workers. The risks, ways to deal with them, possible problems that might occur – everything should be here. It cannot be long – it had better be build in a form of a little encyclopedia, to make every piece of information easily accessible in case of emergency. |
| User documents | User manuals, user guides – what to include here is determined by your customers. Distinguish between different types of papers – brief overviews for basic usage or detailed extensive descriptions of how the system works – depends on what you need. |
Have a brilliant idea for an app? Get a free consultation from our specialists!
Read also:
About the author:
Oleg Roberman, Chief of Delivery at Eastern Peak
With strong technical background and outstanding project leadership skills, Oleg helps Eastern Peak customers introduce competitive advantages and instill productive changes in every process by resolving complex business issues and managing multicultural teams through innovation and creative thinking.
