What are the best practices for documenting software in Agile Development? Documentation, it’s always a question. It is needed with any piece of software, application, process, etc. How much should be documented? When is it too much? There are ways to go about it that make life easier during Agile software development. Building software should not be hindered by documenting what was built. Agile methods require changes and flexibility in documentation practices, just as much as they do in the software development process.
Agile software documentation requires you to navigate complex environments and communicate effectively. You must find a good balance of meaningful information. Avoid too many details. Documentation in agile development also needs to be well organized. Agile teams have to navigate these ideas, and more, to be able to deliver on their goals. The good news is that the Agile tools you have in place for the software work can be leveraged to help improve documentation.
- Develop software that is less dependent on documentation
- Documenting software – go off the needs of the software
- Documentation shouldn’t drive the work, to create documentation in agile process
- Focus on work that was done when documenting software in Agile
- Streamline documentation in agile, to be effective
- Remember the purpose when documenting software in Agile
- Can too much info cause problems?
- Leverage Scrum & Agile Ideas
- Additional reading and eBooks to help with documenting software in Agile
The following are thoughts to help guide useful documentation. Without the issue of over documenting. Ultimately arriving at something that is useful. Use these ideas for documenting software in Agile, to streamline work and be more effective. Use these ideas to help with best practices for Agile software documentation. Adopting more flexible and streamlined documentation practices will help enable and power up the team.
Develop software that is less dependent on documentation
My number one tip for Agile software documentation doesn’t involve documentation. It is build intuitively. Build your software so they it’s easy to use. Also, so it’s easy to figure out. You don’t have to be a UX expert to build intuitively. Make the purpose of menus and buttons easy to understand. Keep navigation simple. Try not to over complicate functionality.
If you are building something that requires extensive documentation, it could be worth looking at simplifying. Having software that is easy to understand will go a long ways. You deliver a quality product that way. You also do not have as much effort needed on documentation that way. Focus on the software itself, to make Agile software documentation easier. If you can develop software and products in an Agile way, you can do the same for documentation.
Documenting software – go off the needs of the software
Think about the needs driving what you are building. The first item I consider is that needs and goals drive the work, which drives the documentation of the work. Documentation shouldn’t drive the work. You should keep your focus on documenting the most important aspects of the work first. This is the task(s) needed most to get that business value.
Documenting software also needs to avoid what is not a priority. If you can, leave those lesser priority documentation items alone until you do the work or they become a higher priority to resolve. This helps to build documentation in a natural progression. This also helps with the organization of the documentation. One note, not documenting future items doesn’t mean not tracking them. A backlog, or parking lot idea, to store those may still be needed. It lets you quickly note them but get back to the work at hand and your top deliverables.
Software documentation should not interfere with software building. They need to be collaborative and complimentary processes.
Documentation shouldn’t drive the work, to create documentation in agile process
The second aspect to consider, is that documentation shouldn’t drive the work. In researching or discovering requirements, we document the existing process. This can be quite the undertaking, as you seek to fully understand and thus fully document. However, that is not an agile approach, as you are attempting to document everything. Agile is about being flexible, and incremental in your approach, and starting with the highest priority.
Documentation in agile should follow suit. Start with goals, create an outline in your mind of the top functionality. Prioritize top work first, for what needs documentation first. Work towards organizing information around that outline. That is a way to streamline and present the information. It also becomes confusing to bounce back and forth between current and future state.
If the documentation does this, the reader will become confused too. Confusing the reader is not in line with Agile documentation best practices. Remember, the reader is often the user, and the software is being built for the user.
Focus on work that was done when documenting software in Agile
You should aim to document what was done. Or, what is useful. A habit to avoid is creating documentation to show that work was done. Not what work was done. In my opinion, this is a habit from Waterfall software development. This was a side effect of a lengthy-time between deployments. Something that should be different in documentation in agile vs waterfall development.
Waterfall development created the need to show work. Often there was much time in between deliverable items. You thus needed to visually present that work was being done. You create lengthy and formalized documents in the Waterfall methodology. For you to show work or to show intended work. That is just part of the Waterfall model. Documentation in Agile processes is different. Being all about the work that was done.
Streamline documentation in agile, to be effective
Tackle needs first. If you do not need something, it shouldn’t be documented. Hence, you should avoid spending much time on future state type items. When you do that, you spend time on items that are not priority work. While it’s ok to discuss, spend less effort on documenting of non-priorities. Place them in a parking lot of idea items. This lets you keep moving forward. You are keeping your focus around top priorities this way. Documentation in agile, like software development in agile, is about doing the right things now.
When you keep things small and focused, you can immediately tackle takeaways. You can move right from collaboration to taking action. Therefore, traditionally, you documented items so that you could come back to it. In contrast, narrow the focus of the work. Then do the work decided. You don’t have to document something to come back to it if you complete it. This is key for documentation in agile development that follows best practices.
Remember the purpose when documenting software in Agile
Documenting software exists to communicate information. Excessive information becomes difficult to read and immediately fails that purpose. You are communicating information in order to work towards a goal. Remember, documentation exists to support the work. To create agile software documentation, remember the documentation is not the work itself. Streamlining and organizing information is key.
Practicing the art of not over-communicating is SO important. Above all, good agile software documentation requires good Agile practices. Creating documentation in an Agile scrum environment should still be about documentation supporting the work. Extend the Agile movement into your documentation processes for best results.
Can too much info cause problems?
“Many of us are finding that despite how much knowledge and information we have access to in our modern times, it’s actually harder than ever before to retain it. That makes us slower when it comes to decision making…”
Oliver Lucas. Information Overload in a Digital World. Eleapsoftware. 12/02/2016. https://www.eleapsoftware.com/information-overload-what-it-is-its-consequences-and-how-to-avoid-it/
Too much information causes issues in our understanding of said information. This is something called information overload. This is often used with workplace and digital communications. Emails, instant messages, and other shared portals lead to constant communication. I argue that this same concept occurs in lengthy documentation. If documentation becomes too extensive, it can be difficult to find the answers you need. It can overload the reader and they are unable to get their needed information.
These concerns make how you go about documenting software all the more important. Keeping to good practices will help enable communication of valuable information, as well as not take away from other priorities. Continuous improvement of your software projects requires learning and adapting.
Leverage Scrum & Agile Ideas
How you go about documentation is no different than learning new ways of building software. Leverage the ideas of Agile and Scrum to help these practices. In the end, it’s about what will help enable your team, and ideas here can help. Adopt Agile documentation best practices to help your documentation be the best it can be. Adopting Agile isn’t just the creation of products and software development. It includes processes for documenting software as well.
Keep software documentation simple and to the point. Build in scalable ways so that you can keep evolving the documentation over time. This let’s the team get something out there to meet immediate needs, and allows for room to grow it over time. Just like the software development. It’s just good Agile my friends.
Additional reading and eBooks to help with documenting software in Agile
Values of the Agile Manifesto can really help you in guiding your Agile documentation best practices. Explore these ideas further in Agile Team Best Practices and Exploring the Agile Manifesto. The Agile development team can leverage these values to help with documenting software created by your project team. Agile principles will help the team build solid habits and go about their work in meaningful and sustainable ways.
For a refresher on the Agile Manifesto, here is a link to the Agile Manifesto. Slicing up of user stories in the ways presented goes hand in hand with a number of the values and principles. Another great piece of information on Vertical Slicing is available here. Vertical Slicing is part of strong Agile development methods. Helping break down the work into more manageable pieces also helps with the documentation for those pieces of work. Make documenting software an easier process to maintain for your team.