Guest Post: Steve Scott manages technical documentation at Flowroute, the leading provider of communication services for SaaS-based companies. He has 22 years of experience in technical writing, working in every type of environment from a 3-person startup to Microsoft, and has written almost every type of documentation—online help for novice users to SDKs for developers. He’s lived in Seattle for 37 years, with stints in India teaching developer writing techniques to non-native English speakers.
There’s so much that can be said about documentation in an Agile environment that it’s hard to know where to begin. In a software development life cycle (SDLC), or any other type of production environment for that matter, documentation is often not at the forefront of people’s minds.
In general, documentation is more often an afterthought, a check box on a to-do list that marks a task as done. In an Agile environment, this is even more pronounced because everything is focused on the actual software development — simply because in a waterfall methodology you’ve gone from a nice languid “Oh, we’ve got a few months to get this done” to Agile’s “oh, we’ve got two weeks to get this done and we’ve overextended ourselves.”
However, in either methodology documentation can suffer: either because the SDLC has gone on so long it’s forgotten about, or things are moving so quickly that documentation isn’t considered the priority.
Reasons Documentation Can Suffer in an Agile Environment
One of the major reasons why documentation might suffer under any methodology is that, in many cases, the intended audience is unidentified. This results in incomplete or not-quite-right documentation; in turn, consumers of the docs complain it’s unusable. Development says “well, no one reads the docs anyway” without looking at the “why” and the cycle repeats itself.
Secondly, there’s this typical thought that you have to lump documentation into bucket types: an integration guide, an operations guide, a web service guide, and so forth. Documentation falls into general catch-alls that might or might not be relevant. Assumptions are made about the type of documentation to deliver, and that’s about it.
As everyone knows, assumptions can regularly be inaccurate. If you don’t know who your audience is, it makes it difficult to write a document; it’s like pin the tail on the donkey: put on your blindfold and hope you hit the target.
A Failure to Identify the Audience
Obviously, it’s easier to write and to deliver documentation when the audience you’re writing for is identified. More importantly, documentation becomes useful when it’s targeted, and if you structure your content so that it can be pieced together as needed, you can publish anything you want in any combination of topics. That is, write documentation in smaller bite-sized chunks that can be pulled together to create a more comprehensive document on the fly (but that’s a topic for another day).
An Environment that Doesn’t Support Consistent Documentation
Because development in an Agile environment can often result in a lot of churn—that is, requirements might change from sprint to sprint, documentation becomes problematic in that a lot of time is wasted. For example, I worked at a company where it was expected that all the “buckets” of documentation would be fully updated at the end of three-week sprints.
That’s unrealistic for any number of reasons; primarily because I could spend an entire sprint just updating what went on for that sprint. Then in the next sprint, they’d change the requirement, and the “buckets” would have to be changed yet again. It’s a waste of time as a writer, and it’s a waste of time for the developers, who were required to tech review the changes.
Waterfall has its own set of shortcomings around documentation, though. In this methodology, by the time it comes to creating documentation, weeks and months have passed since the SDLC began. Teams have moved on to newer things, and now the content that the writer is working on is simply considered legacy. No one wants to revisit something old when there’s something new on the horizon.
So, how do you provide useful documentation in an Agile environment?
1. Work on identifying the audience. Well-written backlog stories go a long way to help identify this audience. I’ve worked in environments where a backlog story would be written: “As a database, I should…”. Anthropomorphizing a database does not identify the audience. A database cannot perform an action unless there’s a user behind it executing the action.
So the story would better be written as “As a database administrator, I can…”. There, the audience is identified. And in the same vein, documentation tasks should be added to the backlogs. Not simply as tasks within a backlog, but actual backlog items identified and added.
Get More Agile Insight
2. Embed the writer with the team. Let the writer drive documentation and respect that the writer knows what’s needed. The more a writer is visible within a team, the more they’ll be treated as a team member. The more s/he’s treated as an active team member, the less likely documentation will be thought of as a check box in a to-do list.
This also helps to more quickly produce documentation. If the writer works with the team as development occurs, questions are asked and answered right there. In a waterfall approach where documentation waits until the very end, development teams have typically moved on to other projects. They’ve checked out, so-to-speak, on the current project.
It’s a bit more difficult for the writer to engage the developer on what the developer might already consider a legacy project. Lags in communication are more likely to occur. Keeping the writer engaged with the team during a sprint goes a long way to ensuring that everyone is working towards the same goal.
3. Get the support of everyone. It’s not just up to the writer to push for inclusion in a team; it’s up to everyone on the team. The Product Owners and the Agile coach need to ensure that the writer is included in all relevant meetings; the Engineering Manager needs to keep the writer included in all relevant discussions; and developers need to provide information and be available to answer questions.
Finally, it’s up to the writer to be visible and vocal and to ask questions. Unlike the lambasted trickle-down economic theory, trickle-down does work for documentation in Agile.
4. Break the mindset of trying to deliver bucket types of documentation. It’s an easy trap to fall into when documenting in Agile, that the focus is on a final documentation set. While it’s perfectly fine to keep that in mind and have a general idea of what you might need in the end, don’t plan the documentation around this. Keep the immediate goals in mind for that sprint.
Start thinking of documentation in the same way that the Agile process flows. You want to provide smaller chunks of documentation around the work done during that sprint and nothing more. In a variation of KISS (Keep It Simple Stupid), deliver smaller bites of documentation. Break the habit of thinking about these buckets of documentation and think about consolidating what’s there—whether it’s on a wiki page, in release notes, etc.–in a single location accessible and visible to the whole team.
To leverage another phrase: think locally, act globally. That is, if you start thinking in smaller bits, the bigger picture will fill out. So, at the end of, start by simply documenting what’s been done during the sprint. Don’t worry about trying to decide what bucket it might fit into.
What’s important is that everyone sees an immediate return on what’s been done and because there’s an immediate return, everyone gets more invested in the success of the documentation. At the end of the SDLC, you can put together a document for any audience since you’ve got the bits all there to quickly assemble something.
Make Your Documentation Useful Again
Finally, it’s good to remember that documentation just doesn’t serve whomever the audience is identified as, whether internal or external, but serves as the record of what happened during a sprint. It allows everyone to see almost immediately see what’s happened, whether it’s two people or 200. It doesn’t need to be formal, and it doesn’t need to be some great product document.
A record, like anything, serves to show posterity for what happened; it can be referred to if any questions arise about what happened, and it can be used to set a course for the future from lessons learned. It can go a long way to making documentation useful and start a positive cycle.
MASTER THE AGILE PROCESS
FREE AGILE COURSE
- Agile Charters
- Handling the XY Problem
- Hiring Agile Team Members
- Handling Impediments
- Creating User Stories