Documentation in Agile – Tips To Help

What are best practices for documentation in agile software development? Documentation, its always a question. It is needed with any piece of software, application, process, etc. How much should be documented? When is it too much? How do you navigate complex environments and communicate effectively? Keep a good balance of meaningful information. Avoid too many details. Documentation in agile development also needs to be well organized. 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 Documentation in Agile to streamline work and be more effective. Use some of these ideas to help with best practices for agile software documentation.

Develop software that is less dependent on documentation.

My number one tip for 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 avoid excessive documentation in agile development.

Documentation in agile development – go off the needs of the software.

Think about the needs driving what you are building. A 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 value. You should not be doing work that is not a priority. You should also not be documenting things that are not a priority. Not until they do become a priority to work on. This helps to build documentation in a natural progression. This 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.

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. 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.

Focus on work that was done, for documentation in agile process.

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 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 waterfall. For you to show work or to show intended work.  Documentation in agile process is 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 its 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.

Remember the purpose of documentation in agile development.

Documentation 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 also 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.

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.

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.

Next up for further reading:

Here I discuss the important concept of breaking up work into standalone pieces. Where those pieces are prioritized and can deliver value. Vertical Slice – Its Crucial To Delivering Value Now

The blueprint here gives some concepts to practice that can help an agile team. A Blueprint for Agile Improvement – 5 Tips to Help

What is the user story and what should you get out of it? Goals of the User Story

Finally, a great post on vertical slicing. Vertical Slices and Scale

Cited above, reading on information overload. Information Overload in a Digital World

Leave a Comment