The landscape of documentation is changing. As with most things, change is inevitable. Documentation is not immune to that. Gone are the days of creating monolithic books that describe in detail every aspect of a piece of software. These days, users have little desire or time to read a full manual. If users go in search of content, it’s typically because they have a problem to solve and they want it solved now.
The documentation market is seeing an increased need for:
- Small, bite sized chunks of content and blog style articles;
- Videos, chat bots, and augmented reality;
- Created and delivered in an Agile environment.
Let’s talk Agile
Unless you’ve been living under a rock (I’ve seriously considered that by the way), you’re likely familiar with Agile methodology.
Agile methodology is commonly used to manage software development. It typically involves development of software in an iterative approach, each iteration (or sprint) delivering a functioning version of the software while bringing customers an opportunity to weigh in, sometimes resulting in a change in requirements.
It’s often mistakenly assumed that being Agile means no planning and no clearly defined requirements. That simply isn’t true.
To be successful with Agile there are typically five levels of planning.
Level One: Product Vision
The product vision should address the following questions:
- Who will buy the product?
- What does this customer look like?
- How will the product address the needs of the customer?
- What makes the product unique?
Using an example format that I found from Geoffrey Moore’s book Crossing the Chasm via scrumalliance.org, a product vision may look something like this:
For the energy-based, safety-minded company, who needs a simple, intuitive agile project management tool, Procedure Accelerator is a procedure lifecycle management solution that brings writers, subject matter experts, and users together to simplify the creation, maintenance, and execution of standard work. Procedure Accelerator will improve best online casino asset life and performance, provide feedback mechanisms for continuous improvement of procedures, reduce information caused site incidents, Accelerate competency, reduce human error, and save you money.
Level Two: Product Roadmap
A product roadmap defines the features and requirements of the product, the priority of the features and requirements, and a high level schedule of when you plan to deliver on them.
Level Three: Release Plan
A release plan defines iterations of the product to be delivered to the customer and when you plan to deliver these iterations.
Level Four: Sprint Plan
Before each iteration of a release, a planning session is held to add detail to the features and define the tasks needed to develop the feature.
Level Five: Daily Scrum
The daily scrum is as equally important as the other levels of Agile planning. A scrum is a daily meeting that typically lasts no longer than 15 minutes and involves three items: What did you do yesterday? What are you working on today? And what is blocking or slowing down work? A scrum master facilitates and helps to keep work flowing by eliminating any blocks.
Agile Documentation – Make It Work for You
“Documentation is as much a part of the system as the source code“
Documentation can be a successful component of Agile project development. Having spent considerable time developing documentation on an Agile team, I have a few recommendations:
Technical writers need to be part of the scrum teams.
During my time as a technical writer, I had the privilege of being part of scrum teams. Being on scrum teams and participating and attending daily scrums meant that I always knew what the engineers were working on. I often would identify items that required documentation before the engineers did.
Technical writers need to participate in sprint planning.
If your technical writing team isn’t participating in sprint planning, how do you know what the documentation deliverables are? How do you get your voice heard? Taking part in sprint planning meant that I could be an active participant in the development process. Together with the engineers and developers, we could more accurately scope out the work for the upcoming sprint. And, the best part…documentation development was part of the planning.
Technical content must be included in user stories.
When technical content is an integral part of software development in an Agile environment, it becomes embedded in the user stories (see Definition of Done). Even better, it’s common to have user stories that focus solely on content development – I’m showing my geekiness here…but it really is a thing of beauty when technical content is afforded the same level of respect as the software/product it’s accompanying.
Definition of Done
Technical content should be part of the user story acceptance criteria and, ultimately, the Definition of Done.
This one was critical to my success as a technical writer on the team. Nearly all user stories included acceptance criteria for end-user documentation. If the end-user documentation wasn’t completed, the user story wouldn’t get accepted. That meant that the rest of the scrum team had a personal stake in my successful completion of the related end-user documentation. And because they had a personal stake, I got their assistance when I needed it – via technical expertise, content reviews, and more.
As the marketplace continually evolves and gets more competitive, there is an increasing need to regularly iterate on products and their accompanying documentation. Adopting an Agile methodology supports this need. When well planned, Agile can work for your product and your documentation needs.
Developing a Voice for Technical Documentation
More and more, companies are using technical writers to create content for a product using the...
Creative Technical Writing
Creative and technical?
Your Brand Isn't Just a Logo
I’m sure most of us can identify a company’s logo without too much difficulty. Some logos are so...