Documentation in an Agile Environment

Posted By: Tara Coulson

Fellowship Technologies’ Product Development group has been developing features and functionality for Fellowship One using Agile Software Development for two years. The methodologies involved with Agile:

  • encourage frequent review and adaptation
  • promote teamwork, self-organization and accountability
  • promote rapid delivery of quality software
  • focuses efforts on customer needs and company goals

Scrum teams form to work on particular user stories requested by a product owner during a two or three week sprint. Each scrum team is typically made up of developers, quality assurance and documentation specialists. The goal for the end of each sprint is to, as a team, work to produce working software.

How Does Documentation Fit? Lessons Learned

The very first lesson I had in this subject is that there are two types of documentation and they are completely different things! The first type of documentation is project related or, in other words, what must go into the sprint to identify exactly what the product owner is expecting and what team members are committing to. The second type is end user documentation, which provides direction on how to use the software.

Project related documentation consists of user stories. Typically written in the voice of the person who has requested or will benefit from the outcome, these stories define at a high-level, what is needed. An example of this is:

As a Church Member, if I have previously created a WebLink account, I need the ability to convert it to the new email format. If I have never created a WebLink account, then I need the ability to create one in the new email format.

Team members break this story down to manageable tasks such as:

On login, check user login table first for existing login, redirect accordingly.

The second type of documentation is strictly for the end user. What the end user needs to correctly use a feature. Using the example above, the documentation will include instructions on how to convert your existing WebLink account user name to the new email address format and how to create a new WebLink account. Notice, there’s nothing in the story or task that relates to this; however, there are clear rules as to the expected behavior, which leads to…

The second lesson learned is that you must create documentation while the features are being developed. You cannot wait (as in the old Waterfall days) to create your documentation when the software or feature is completed. This was the hardest hurdle for me and my team to overcome. I, particularly, had been trained by previous companies (and even when completing my concentration in technical writing) to create documentation only after a product was fully functional and ready to release to users. This training is contrary to Agile conventions. In order to have completely working software at the end of a sprint, we have to have end user documentation to complement it; not just for our external end users, but for internal employees as well.

Benefits - Far Greater than the Pain

Overcoming lesson two was painful! You could often hear me say things like, “I’m writing fiction” because if I couldn’t see it how could I document it? I had to learn to trust the team to follow the rules created in the user story and task documentation. Learning to trust and work together to get to a goal is one of the best benefits of working in a Scrum team.

The other benefit to all you writers out there is that you finally get a seat at the table. And, wonder of wonders, you are actually wanted there! Those of you who have worked with tough subject matter experts (SMEs) in the past will be astounded to realize they aren’t actually tough at all, they are just three hundred steps ahead of your old Waterfall ways. You are making them recall code they wrote long ago, when the developer’s entire focus (and rightly so) is on what they are doing now.

Having a full seat at the table allows you to help develop user stories, tasks and even have your own stories and tasks! If you have always lamented the fact that your developers have no clue what it takes to produce documentation, then this is the place where you will be vindicated. Believe me, when I saw all of the documentation-related tasks associated with a single user story, I began to understand why my team was always so busy. We do a ton of work; let the hours for that work be counted!

Finally, because Agile Scrum embraces iteration, you are writing far less during a single sprint than you do with Waterfall methodology. When an epic or theme is all said and done, you may have a gigantic documentation set but you will have built it slowly, sprint by sprint with the full support of your team. No longer will a feature or function surprise you because it was “thrown over the wall” at the last moment. You won’t have these moments, because as a fully-bona fide team member, you will be invited to all planning, daily standups, change meetings, and sprint reviews, which is where you should have been all along.

Tara Coulson joined Fellowship Technologies in 2004 and has served as the Manager of Education Services for the past year. Check out our documentation by clicking the help icon in the upper-right corner of each Fellowship One page.


Posted In: Tips,

No one has commented yet. Be the first!
Commenting is not available in this channel entry.


Previous Posts:

Subscribe to the RSS feed!