Documentation of work processes and design decisions is a form of organizational memory: it prevents teams from running around in circles — repeating mistakes or simply arguing over the same topics again and again. A challenge faced by UX practitioners working in Agile is the notion of minimal documentation — in an attempt to work fast, teams stop writing down important information. Alternatively, too lengthy documentation runs the risk of being ignored. In either case, the result is time wasted to recall information or retrace design decisions instead of experimenting and iterating to improve the product for end users.

This article discusses how to document and communicate the right types of UX details throughout the Agile product-development process. Teams adopting these practices won’t be overwhelmed by excessive documentation and will easily remember what’s important. 

Documentation Throughout Agile Product Development

Regardless of the product development phase, keep these factors in mind with UX documentation: 

  • Who’s the audience? The answer to this question should drive the level of detail included in the documentation, what information is prioritized, and how and where it’s communicated. Choosing the level of information granularity that is right for the audience will prevent wasted effort and make the information easily digestible.
  • What’s the purpose? Is the documentation meant to provide background context, evidence, or rationale? Is it to help the team remember something later? Is it to report progress? Understanding why the documentation is needed in the first place will help you see which details to include.  
  • Quality over quantity: Less is more: don’t document every single detail or meeting, but just enough to clarify intent or direction, provide a recap, justify a decision, or outline how something should work.
  • It’s iterative and ongoing: Don’t wait until the last minute to document details; do it along the way as you’re researching and designing to challenge your own biases and rationale, keep your project manageable, and produce better outcomes.

When and How Should I Document?

Though Agile favors individuals, interactions, and conversations over heavy documentation, there are two cases when it is especially important to augment discussion with lightweight documentation:

1. Before something begins — for example, before discovery or other user research, an event (formerly called ceremonies), or sprint. Lightweight documentation provides context, creates shared understanding, and gives the team something to refer back to when questions arise. For this type of documentation:

  • Include a plan of what you will do.
  • Keep it short — use a one-page bulleted plan or summary.
  • Communicate how whatever you will do will impact the team.
  • Outline who’s responsible for objectives or artifacts.
  • Include dates to timebox input and the effort.

2. When something changes — for example, if a design or feature needs to go in a different direction or if the sprint goal, releasable increment, or the development process are modified. Because Agile is more about responding to change than following a plan, lightweight documentation in these instances will help the team quickly remember when and why changes happened and prepare it to respond better and faster. In these cases:  

  • Share changes incrementally as you work.
  • Focus on only the essential.
  • Use existing tools and documents to add detail (e.g., for design solutions, design systems, wireframes with annotations, Slack channels, Jira/Confluence, other shared document or code repositories, etc.).
  • Outline who’s responsible for next steps, action items, and final decisions.
  • Include dates to timebox decision making and subsequent efforts.

Communicating Ongoing Learning and Progress

It’s also important to inform the team of progress toward goals and ongoing user feedback received. The UX team can create these progress reports on their own or partner with product owners or managers to retrieve and report the data collaboratively.

Don’t bombard people with heavy presentations, overly detailed research findings and feedback, or vague charts and graphs. These are wasteful both to create and to consume. Instead, send regular and concise progress reports — through a weekly email recap. Give it a catchy and noticeable name, such as “UX Feedback Friday,” so people look forward to receiving it each week. Keep the details light and focus on the metrics that your business and team care about. Include any positive and negative qualitative feedback the team should know as well. 

Retrieve quantitative data from analytics or business-intelligence platforms and recap qualitative insights from recent user research or feedback shared on platforms where net-promoter or customer-satisfaction scores are tracked. Group feedback into key themes and share the most pressing pieces.

Weekly progress reports should include the following:

  1. Team or product name
  2. The date range or timeframe the data reflects
  3. Progress toward quantitative metrics
  4. Positive qualitative feedback or behavioral observations from user research
  5. Negative qualitative feedback or behavioral observations from user research
  6. Culture builders such as team happenings, trends, or tools to investigate
A weekly UX progress report communicating feedback and progress toward metrics.
Weekly UX progress reports build rapport with the team and prevent information overload when it comes to sharing feedback and tracking metrics. Delivering progress and user feedback in digestible ways and at regular intervals helps the team see the true impact of its work and where to focus next. The 6 elements of the progress report — (1) title, (2) date range, (3) quantitative metrics, (4) positive qualitative feedback, (5) negative qualitative feedback, and (6) culture builders — are all called out in this example progress report.

Benefits of Good UX Documentation and Communication

Good UX documentation ensures that everyone stays informed and helps Agile projects run smoothly. When the right information is captured at the right level of detail and in the right places, it’s not wasteful. Good documentation leads to better and faster decision making, aids in presenting and justifying design decisions, and reduces the cognitive load for the team by acting as a form of external memory. Keeping thought processes organized also builds trust and credibility for UX with stakeholders. In large organizations, good UX documentation that’s properly shared also helps with crossfunctional coordination.

Conclusion

Documentation is too often deprioritized in the name of agility or speed. Writing things down is a critical part of thinking through your UX work and prevents your team from making the same mistakes twice. Start documenting the right types of details now to move faster later.

For more on Lean approaches to documentation, user research, and incorporating UX into Agile product development, take our Lean UX & Agile course at the UX Conference.