Documentation in an Agile Environment
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,
- Include Requirements & Contribution Sub Types
- User Case Story from Hope Community Church
- Group Search Categories and More
- Account Creation
- Single Sign On Functionality Exposed
- API Communication Value Changes
- API Enhancement: Create and Edit Groups!
- API Enhancement: Requirements Exposed
- Resource Versioning
- Enter Visitor Data via Your Church Website
- Fellowship One & Planning Center Online
- API Libraries and Sample Code
- Building a custom login for your church website using the API
- Roll Foward!
- The Agile Triangle
- Conversation Paralysis
- Picture this, image updates & creates through the REST API
- A REST API double shot : Groups and Events realms
- Increasing Software Delivery by 500%
- Quick people API realm update
- Introducing the new REST API giving realm
- Raising the bar…
- Building a Deployment Pipeline
- The World of Dev Craft
- Running Tests in Parallel with Selenium
- Abstracting Your Code to Remove Duplication
- Documentation in an Agile Environment
- Drowning in Debt
- Intro to Ruby on Rails
- API Strategy & Roadmap
- Staging/Sandbox Environment is Back up!
- Downtime in Sandbox/Staging Environment
- Android & OAuth
- F1 API Static Library with Objective-c
- Programming in F#
- NoSQL: HuMONGOus Benefits (Part 2)
- Our Scrum Team Structure
- SaaS & BI - The History & Future
- Getting Started with Android
- NoSQL: Leaving Schema Behind (Part 1)
- Your Feedback…and a $25 Gift Card!
- A Scrum Ceremony? Is this a wedding or something?
- Variables in PHP
- Data Exchange API Fixes
- F1 Check-in on the iPad
- Be the first to get the news & tips!
- An Introduction to PHP
- Working with Pop Up Windows in Selenium
- List Comprehension
- Source Control: A Time Machine For Your Source Code
- Developer Conference…Lower Price, Same Great Content!
- The Quality Assurance Team
- How does Fellowship Technologies manage complex projects?
- Developer Conference coming in May!
- Sandbox Refresh Complete
- Sandbox Refresh This Week
- Updates coming to the REST API
- Sandbox Environment Down Time
- F1Touch :: Fellowship One On The Go
- Under the Hood
- Sandbox Refresh Complete
- Sandbox Refresh Tomorrow (Oct. 2nd)
- Fellowship One Developer Forums
- Ten Commandments of API Consumption
- REST API Enhancements / Fixes deployed to Sandbox and Production 09.09.09
- Data Exchange URL cut-over complete
- Important Data Exchange URL changes
- Ron Nom Nom
- How to get started using the REST API