Technical Writing and Agile
I’ve been mulling over the role of the technical writer in an Agile team for some time. I wanted to jot down some of my thoughts on the role and its challenges, as well as explore how to overcome those obstacles. I should stress that I've experienced working in an Agile environment as a Developer and a Writer in two different companies, so while I am used to the process, I am conscious that Agile seems to work differently everywhere. For the purposes of this article, I’ll be referring to SCRUM methodology, as this is where my experience lies, both as a developer and a technical writer.
It is a misconception to see Agile as a methodology for producing a finished product. Agile is a tool for building software quickly in a more manageable way, but its emphasis is on development-driven development. It nods to test and documentation, and aims for a higher level of excellence in a code base, but it is not a manifesto for testing or for documentation. In fact, the original manifesto clearly outlines the need to prioritise development over documentation. Some writers balk when they read this, and are almost offended at the assertion that the documentation should be sacrificed in the name of code, I ask you, if there’s no code written, there is no product, and if there is no product, what is there to document? I have seen people brush this off as referring to internal documentation, I don't think it does. The focus in agile is on working software, and rightly so.
Technical writing in an agile setting can be as difficult as technical writing in waterfall. Instead of one huge panic and rush to produce documentation at release, there is instead an incremental and iterative panic. Documentation is generally driven by development and if development has not even started, there is little information for a writer to work with. Like testing, in a traditional development-driven setup, documentation comes after the fact. In the course of a sprint, documentation will occur at different stages on a story-by-story basis, but almost always after development. Unless it’s a small and specific defect, like a UI element name change, or a change in the name of a command, the documentation comes last.
So, if Agile is about development, and documentation almost always comes last in the process, is it possible to be an agile technical writer? That concept is subject to much debate. In my view, the term “agile technical writer” is misleading. The writer supports the agile development by delivering updated documentation. They are still separate from the agile process, but they can serve as a first line of testing by beginning their work concurrently with the QA team. This is the best way to keep up with sprint-to-sprint changes and - hoo boy - there will be changes.
One of the main struggles of being a writer in an agile setting is that the documentation is constantly being changed as the software is being updated. To counteract this, there are some who suggest leaving the documentation to the end of a release cycle. I can’t imagine the stress of shoving months of documentation work into a week at the end of the release cycle. This is also not strict agile. Agile should allow for the release of working code every sprint. If you’re releasing working code, then you need to document any applicable changes. For this reason, I always document every sprint, as comprehensively as possible given available resources. I find it easier to work with an existing skeleton document, adding changes as they happen. The downside of this being that the writer will sometimes have to jettison entire sections of documents, or entire documents.
Let’s take an example, say you’re working on Backtrac, a new software product. The first iteration is going well, the product is going to be a simple and easy way to recall embarrassing text messages. Then in the middle of sprint two, the team realizes that there is another product that does the same thing. They’ll need to revise the feature set so that they offer something unique. So they add a recall embarrassing photo feature that automatically searches the web for any photos uploaded post 2am on a Friday night. Things are going great until sprint 4, where the team decide to add email functionality, because who hasn’t sent an embarrassing email to the entire company. Meanwhile the writer may well be circling like a headless chicken between various developers and product owners, and scrum masters, simply trying to get the job done.
How do you avoid this problem? You could point the finger at poor planning, but one of the core tenets of Agile is the idea of continuous change, including changing requirements. There are some steps a technical writer can take to avoid being overwhelmed by change:
Know your product inside out and back to front.
If you know the product, you will more easily understand possible changes. Don’t make the mistake of relying on other people to tell you about the product, read any technical specifications you can get your hands on. Review marketing material, this is the first thing your user is likely to have come across while digging for material online, and will help you to understand the product from your user’s perspective. Speaking of which…
Fixate on the user’s point of view
How will the end user that is reading the documentation approach the product? If you can get your head around how the person reading your document will use the product or feature, then you will be able to understand what information they will need to hand. There is no point creating the most innovative video experience for your customer, if what they would really like is a PDF on their iPad. Observe your customer using documentation if at all possible. Notice any unexpected behavior or “hacks” they are using. Incorporate those into your documentation. Agile, as per the manifesto, should put customer collaboration at the forefront of all efforts, and asking your customer might be the difference between great documentation and poor documentation.
Speak to developers.
Sometimes, technical writers are intimidated by talking to developers. This is especially common where the writer has little experience with writing software. This is where knowing your product inside out from the user’s POV will help; it makes it easier to ask very specific questions. It’s also very useful to have the perspective of a developer. They know the product inside out from the ground up. Be honest, if you don't understand something, either ask the question or take a note and research later.
Write first. Ask questions later.
Once you’ve done your first investigation into the new feature or product, begin to write. It doesn’t matter if it’s vague or if there are holes. It’s the frame with which you will communicate to developers and QA engineers. If possible, and you should be making it possible by working on point 3, you want to sit with developers and go through this draft document. At very least, you want an email chain and IM log that examines what you’ve written, and what else might be needed. Commented PDFs or Wikis are handy for this. It’s easier for everyone involved to spot missing information in an actual document, rather than trying to imagine a conceptual document.
Ensure that documentation is included in stories.
Either create stories for documentation or add tasks to development stories, either way, make sure that documentation becomes a part of the scrum process.
Finally, I advise reading the Agile manifesto and learning it very well. You need to know the rules of the system you are working within. Good luck and stay agile!
Missed anything? Comment below please!
