Log in
Log in
View Engineering Jobs

Agile Documentation: Keeping Your Team in Sync in an Agile World

Monika Gilmore

Reading time: about 4 min

Topics:

Remember writing a detailed lab report or paper in school? We’ve all been there, and I doubt many of us really enjoyed it. Process and product development documentation can leave that same sour taste in your mouth if it’s just documentation for the sake of documentation. Documentation can take hours and hours to create, and when you're typing endless words and sets of data just to satisfy company-wide requirements, it becomes even more painful. Despite the time and tedium, documentation does present several benefits that make the process necessary, even at small startups. When it’s created properly, it can lead to more clarity and better work and teamwork. Documentation helps us keep objectives clear and keep new features in a reasonable scope while still solving the core problem. But documentation has changed. The term no longer means the same thing to all people in all organizations and job roles. While some big companies may require 100-page investigations and reports, in an agile environment like at Lucid, we try to be more flexible in the type of documentation we make and use. Don’t get me wrong—we take our documentation seriously, just not too seriously. We have some agile documentation practices in place to make our lives and our co-workers’ lives easier as we build, review, and look back at projects. We have standard ways of handling pre-build project requirements, including customer interviews, research data, and specifications. We have also standardized the way we review A/B test results, which then come in handy when you’re looking at historical information on what you can expect a new test to do. But we also recognize that not every project is the same, so we adapt to whatever type of product management documentation the project calls for. If the documentation helps us complete the project and also communicate the results of that project to other parties, then it’s useful, agile documentation, right? From my experience, no one reads endless wiki pages on a project anyway, so we often create quick summaries and then add detailed information where it’s necessary and useful for any parties involved. For example, we recently built a new feature that involves importing a new file format into Lucidchart. It was a mess of different factors to consider—how should we handle text, lines, line styling, shapes, custom shapes, images, colors, etc. You can imagine how complicated that would be to document.
A flowchart for managing shapes we imported into Lucidchart. Includes color coding for easy reading. , opens in a new tab
A comprehensive flowchart for managing the properties of shapes that we needed to import.
Luckily enough, Lucidchart, the very product we build, helped us document the feature in diagram form. We were able to sub-categorize the different line styles, shape types, colors, and more that we needed to import, outline dependencies, and consider edge cases in one document. This was a living document, not just something we made to satisfy a process requirement. Yes, it came with additional documentation for customer requests, event tracking requirements, messaging requirements, and error collecting. But this document was the meat of it. We opened this diagram every single day for some purpose. Sometimes it was just to get the general pulse of where we were at, how much additional work we had to do to meet our release deadline. Other times, it was to see what potential areas could be related to the feature we were testing.
We managed the line variations we needed to import using this flowchart. , opens in a new tab
We categorized the type and styling of lines for our import process.
Even now, after we have released the beta version of the feature, we look at the diagram to see what pieces we need to change to improve our import functionality and what features we support for the sales and customer success teams. In short, this document hasn’t died somewhere in the depths of Google Drive or Confluence. For my team, the key to successful documentation is simple:
  • It serves a clear purpose and isn’t just documentation for documentation’s sake.
  • It evolves as we need to make changes.
  • It exists in whatever form we find the most useful for the purpose its serving.
Try adapting your documentation process to your agile work practices. If you write up and store information in a way that is useful for your team’s needs, then it will actually be used and maintained. 

About Lucid

Lucid Software is the leader in visual collaboration and work acceleration, helping teams see and build the future by turning ideas into reality. Its products include the Lucid Visual Collaboration Suite (Lucidchart and Lucidspark) and airfocus. The Lucid Visual Collaboration Suite, combined with powerful accelerators for cloud and process transformation, empowers organizations to streamline work, foster alignment, and drive business transformation at scale. airfocus, an AI-powered product management and roadmapping platform, extends these capabilities by helping teams prioritize work, define product strategy, and align execution with business goals. The most used work acceleration platform by the Fortune 500, Lucid's solutions are trusted by more than 100 million users across enterprises worldwide, including Google, GE, and NBC Universal. Lucid partners with leaders such as Google, Atlassian, and Microsoft, and has received numerous awards for its products, growth, and workplace culture.