Words that Work

The familiar style of the anti-procrastination jingle works better for testing products than for writing about them. ‘Test early, test often’ makes a lot of sense. ‘Writing early’ also makes sense, but the ‘writing often’ doesn’t have to follow.

Some development teams wait until a new product is fairly mature before involving technical writers. Perhaps some of the reasons include:

• The feature set is incomplete, so it’s not ready for the writer.
• During development the product is prone to crashing, so it isn’t ready for the writer to see it.
• There are rough edges, where we aren’t really happy with the behaviour, and we might change something, so there isn’t any point getting a writer to describe the behaviour.

All these patterns of thinking consider the writer to be an outside party to whom the finished product is handed on. On the other hand, what are the benefits of considering the writer to be an important part of the development team, and involving them earlier?

• Involving a writer early helps your time-to-market, by avoiding crammed in documentation phases at the end of development, and potentially deadline over-runs.
• More of the writing will be able to be reviewed earlier, resulting in less pressure on the other team members as the release deadline approaches (note that developers generally don’t have time for something arguably ‘unproductive’ as reviewing documentation on the days leading up to a release).
• A good writer will be able to help the development team recognise what aspects of an awkward behaviour are undesirable, because if it is painfully difficult to write about, it’s probably painfully difficult to do.

A good writer is going to easily cope with gaps in the product’s functionality, instead using the requirements, issue tracking tools, and other information from developers as necessary, or writing around the gaps and coming back to them when the rest of the development team also turns their attention to these areas. The writer does not have to work through the product in a linear fashion. At the same time, they will use their knowledge of what is going to appear in those gaps to ensure that the final document will be a cohesive whole, instead of sprouting appendages and afterthoughts.

A good writer is going to be unfazed by the odd product crash during development. They are professional, just like the rest of the development team. Their eyes on the product can even serve as additional informal test capacity, as the writer ferrets around into each nook and cranny of the product’s feature set. The tech writer discovering a bug isn’t a bad thing, it’s an early discovery that can then be dealt with productively, just as it would be if found by any other member of the dev team.

Will beginning the writing earlier result in more time being consumed in writing, perhaps due to rework die to changes in behaviour? If there is additional rework, the additional cost of this time is more than offset by the time saved by involving the writer earlier, so they are included in development discussions, which reduces the need for developers to recap to the writer why things are the way they are. It is also offset by the writer using their understanding of how the product is being developed to avoid areas where future change is anticipated.

More development teams are using agile development strategies to deliver functionality in short increments. Involving a writer as each of these increments gets delivered can ensure that each complete vertical slice of the product, including the documentation, is delivered. Often, the work involved in writing the documentation for the features a team delivers in one sprint or iteration does not warrant having a writer on the team full-time. However, it is better to involve a writer in the sprint as it happens, to be part of the sharing of information, and so that the documentation produced can form part of the ‘definition of done’. This will produce better writing matching the features added, than pushing developers to do their own documentation (see Do we even need professional writers?).

{ 0 comments }