Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

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

DZone's Guide to

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

Going Agile doesn't mean getting rid of documentation, but just making it more active, more breathable, more...Agile. Find out how here.

· Agile Zone ·
Free Resource

Adopting a DevOps practice starts with understanding where you are in the implementation journey. Download the DevOps Transformation Roadmap. Brought to you in partnership with Techtown.

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 for 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 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 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 it's 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.

Take Agile to the next level with DevOps. Learn practical tools and techniques in the three-day DevOps Implementation Boot Camp. Brought to you in partnership with Techtown.

Topics:
agile ,documentation ,diagramming ,agile documentation ,chart ,visualization ,flowchart

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}