The software industry has largely moved to Agile methodologies over the last decade. However, businesses often struggle to deliver documentation using the same agile methodology that works so well for their code. Let’s delve into a few of the reasons for this.
We have a huge number of tools available to support teams in planning, creating, and polishing their projects in small, easily-deliverable chunks. However, we often leave our documentation languishing in environments left over from the 20th century, designed for large-scale waterfall development. Producing documentation can be a day- or week-long process that eats up valuable sprint time.
Find documentation tools that are compatible with Agile methodologies.
Once upon a time, software documentation was a matter of writing a manual, constructing a table of contents, and maybe – if the end user was a very lucky duck indeed – thoroughly indexing the text. The user would receive manuals in the box, in print form or on CD as a PDF. Sometimes they could find help files embedded in the software that explained confusing fields or functionality. This style of documentation is horribly dated, near-useless with today’s technology levels, and incredibly difficult to keep current. However, many businesses are still using similar design models, due to legacy documentation suites or an inability to reshape and reimagine their informational strategy.
Recreate your documentation model to suit your users and production schedule.
Our developers can write the documentation
This is not a swipe at software developers. Lovely people. Some of my best friends are developers. But your average developer is not a writer. When they talk about the product they work on, they typically do so from a developer’s viewpoint. This is great if their readers are also developers working on the same piece of software. End users, on the other hand, are often left confused by weird word usage and frustrated that the information they need wasn’t even considered as a possibility by people who already know the software inside and out.
Let your coders do what they’re good at, and hire a technical writer with Agile experience.
Creating agile documentation
You want your end users to have access to relevant, useful, up-to-date information on how to successfully use your product. So you need to think about some key points:
- what your technical documentation will look like.
- how to produce that documentation as development occurs.
- the tools that you’ll use.
- who will create the documentation.
Given that I’m a documentation consultant, you probably won’t be surprised to read that I recommend bringing in an expert to help you figure out this process. The documentation tools that work brilliantly for one business might be a huge headache for another. The medium(s) that you use to disseminate information will depend in large part on your target audience and their habits. The people that you need to create the documentation – and their skill set – will vary hugely depending on the other two criteria.
Save yourself time, money, and misery – start by asking a documentation expert to work through your unique requirements and guide you to processes and tools that will best enable you to communicate information to your users.