You don't do documentation, so why should you care about it? How about missed deadlines, buggy code, and unhappy users?
Believe it or not, an agile approach to documentation can address all these problems—but only if the whole agile team is on board. Here's why everyone should care about documentation and how to do documentation right.
Waterfall documentation makes your job harder
Under the waterfall technique, the development team has little reason to care about documentation. Documentation is usually handled during the final phases of the project, along with testing and quality assurance (QA).
This approach doesn't work with agile. If you wait until the product is nearly done to start documentation, QA might spot bugs that require last-minute revisions to the software. Since the product is close to delivery, any updates to the documentation must be made quickly. This can lead to documentation that is riddled with errors.
Also, when the product is near completion, the engineers involved will be moving on to new projects. Trying to track them down to obtain information on a project they are no longer involved with becomes difficult.
Pulling engineers off their new projects also disrupts the schedule of those projects. It's also inefficient, because the engineers will have to dig through old work to answer questions.
Writing documentation the agile way
Taking a more agile approach to documentation can solve all these problems. Even better, it can help you create bug-free code that your users will love.
1. Meet launch deadlines by documenting faster
Agile can involve the writers in the project from the start, in a process known as continuous documentation. For a first-of-its-kind product where most of the material must be written from scratch, continuous documentation ensures that the large volume of documentation gets written, reviewed, and delivered on time.
That's not to say documenting a moving target is easy. I'm involved in writing documentation for a big data product. Over time, a number of features—along with their API calls—got eliminated due to time or resource constraints. The solution is to delete the material, move on, and use version control to keep the deleted material around for reuse in a future update.
2. Reduce your workload
Documenting in parallel with development makes it easier for engineers to answer questions. They are still in the thick of development, so they can explain their work without going into the archives.
When the engineers and writers collaborate in an iterative process, they can learn from each other and make the whole process more efficient. For example, if the technical writers have a lot of questions about a particular API, the engineering team can provide information about similar APIs up front to avoid having to go back and forth.
3. Improve features and discover bugs
Getting technical writers involved early is a great way to get feedback on your design. If your documentation team can't figure out a feature, your customers probably won't either.
Having the technical writers involved during the sprint can also help QA discover problems. To me, part of documenting an API call properly is to try it out with test code, and—for a complex call—to also provide sample code. Working this way, I have on occasion discovered bugs or confirmed that a bug fix applied during the sprint works.
For example, in attempting to verify that an API call filtered out specific information, I discovered that the filter parameter didn't work at all. Fortunately, another API call could return similar information, and so I added an operational note that instructed the developer to use the other API call when necessary.
This sharing also works the other way: QA often points out the idiosyncrasies in invoking certain APIs to me, and I make sure this operating information appears in the documentation. A quirky API call that isn't thoroughly documented can cause all sorts of support problems.
Making agile and documentation work together
From personal experience, for continuous documentation to work properly under agile, a few principles must be observed.
1. The documentation effort must be baked into the agile process
The easy part is to define the document writing as a task in agile. The hard part is budgeting the resources, including time, personnel, and money, for the task.
If you find yourself questioning the budget, consider this: you can either invest up front and get the content you need, or you can pay support costs on the back end, because the documentation effort was starved for resources and now you have poor or nonexistent documentation. There's no way to avoid the cost—you just get to choose where you want the pain point to fall.
2. Everyone contributes to the documentation effort, for each sprint
I see engineers cringing at this. Many of them are great coders but poor writers.
However, make it clear that you're not expecting a magnum opus from them: They should only capture key details about the APIs and modules they're working on during the sprint. Bullet charts will do. If necessary, you can follow up with them for additional information.
Also, any operational notes, such as the discovery that the software now requires specific hypervisor settings, must be included. This lets me neatly segue to:
3. There should be a "point person" who manages the documentation effort
This individual collects the information from the engineers and merges it into a cohesive document. Ideally, this should be a tech writer who understands the issues involved in getting content written and who can manage document version control.
At the start of the project, this person would also pick the writing tools, such as Microsoft Word or a DITA editor, and what documents need to be written. This person should be dedicated to this task and this task alone. (See point one).
4. The tech writers need to be engineers
There are many reasons for this requirement. A tech writer with an engineering background can talk shop with the software engineers and get the key points without requiring someone to explain in detail to the writer what is going on. An engineer can readily learn—if they don't already know—the technologies the project uses.
For example, over the past year I've had to describe REST and SOAP interfaces and how to implement secure connections using tokens or cookies. If the writer has programming experience, all the better, because they can be given source code to study and can concoct any sample code.
5. No person is a silo
One of agile's strengths is that the regular scrums give every team member a clear picture of what's going on over the entire project. This can give the tech writer an idea of what software modules have stabilized and therefore where to commit their efforts on the next sprint.
In addition, since many complex software systems consist of black boxes communicating with one another, the tech writer can use this big picture to produce an overview document that explains the interfaces and data flows, which will be valuable to the operations team.
How to make agile documentation a success
There's little reason not to integrate the documentation effort as part of an agile process. Like any other software project, the key is to commit the resources to the effort.
Because the tech writers are working closely with the developers and QA testers to collect information, these people should be engineers themselves. That might seem like the most daunting task of all: finding an engineer who's both knowledgeable in the field and enjoys writing. They're out there, and they should be members of every agile project.
Keep learning
Take a deep dive into the state of quality with TechBeacon's Guide. Plus: Download the free World Quality Report 2022-23.
Put performance engineering into practice with these top 10 performance engineering techniques that work.
Find to tools you need with TechBeacon's Buyer's Guide for Selecting Software Test Automation Tools.
Discover best practices for reducing software defects with TechBeacon's Guide.
- Take your testing career to the next level. TechBeacon's Careers Topic Center provides expert advice to prepare you for your next move.
