Agile Misconception #2: We Don’t Need Documentation

Documentation means a lot of different things to different people. I’ve also found it’s one of the top five topics to cause a developer to cringe.

If you’ve used a waterfall software development process, you’re all too familiar with documentation. From requirements to systems architecture to design, you’re creating documentation at every step of the process.

There is a common misconception that documentation should be done away with entirely in Agile development. I strongly disagree. There should still be some documentation. The hard part is finding the right level for your project to ensure it is successful.

Agile Documentation Basics

Agile values “working software over comprehensive documentation.” So what does that mean?

  • Documentation will not account for every nuance throughout the project. It is intended to start the conversation and provide enough information to begin development.
  • Documentation is not set in stone. Teams can use it as a guide, but they have to be flexible and willing to change based on conversations, feedback, and new information learned along the way. The trick is not to invest so much time in documentation that your team becomes more attached to the artifact than to the actual work and goal.

Agile Documentation Ideas

With Agile, the level of documentation can vary. Here are some things that might work well for your project.

Annotated wireframes

Annotated wireframes are designs that lay out the workflow and use for each feature. These often turn into stories, but the visual representation is useful for developers/testers to understand what to build and how it should work.

User stories

I won’t go into all the details and advice on how to write user stories (there are many more blogs for that). However, you can think of user stories as placeholders for conversation. They provide enough detail to start conversations and get developers coding and testers testing. The key is to find the balance between documenting every detail and letting some of the details shake out as work starts to progress.

Architecture diagrams

Visual diagrams are useful to provide an overview of how all the pieces will fit together. Architecture diagrams specifically don’t change often, and they are a good way to identify integration points. They help identify areas where other teams will do work and identify dependencies. They can also be useful resources to onboard new team members.

(Business) process diagrams

These diagrams show how an organization will use the tools/technologies your team is building. They can also help your team understand how to think about error handling, data entry/management needs, and the needs of various users.

Hand-off/transition documentation

This item can vary in its format, but it should include a summary of the completed work, key decisions, and the way things operate.

What Should You Document?

Here are some questions to assist you in determining other aspects of the project that might be good candidates to document.

  1. What items will not change frequently?
  2. What does (or would) your team spend time explaining to new team members?
  3. What items or processes would be helpful for the whole team to know?
  4. What is particularly complex about the system?
  5. Are there parts of the systems that are used infrequently and hard to remember how to approach?

No team I’ve ever worked on is excited to spend time on documentation—you can always find a rationale (or excuses) to de-prioritize it. However, honing in on the documentation that sparks conversation and collaboration can help teams see the value of taking time to create the content.

Don’t miss the first post in this series: Agile Misconception #1: Deadlines Don’t Exist.