Planning your deliverables

I don’t like making presumptions, something that I learned early on in my technical writing career, but I am going to presume that anyone who reads this knows that they should be planning what content they produce before they start writing. You do, right?

A basic information plan will include knowledge about the audience, the main areas of the information that need to be covered for the project/release, as well as outlining the purpose of the documentation and any media and design considerations. Finally you’ll most likely provide a definitive list of deliverables, be they printed documents, PDFs or online help.

It’s this last area that I’m currently working on.

Our product has undergone some exciting changes, and the previous set of documentation was both very document-centric and , in my opinion, badly structured. We are shifting more towards a ‘traditional’ SDK approach and as such a lot of the existing documentation needs to be adapted accordingly.

Thankfully it’s largely an exercise in restructuring the documentation rather than completely rewriting anything, but it still warrants discussion with the audience as to how best to present the information they require. In that respect I’m lucky to have direct access to a representative portion of the intended audience as the bulk of the audience will be our own staff.

The functionality available in our development kit is broken into sections, with the documentation split along similar lines, and as such whilst the information in the current documentation is fine, it no longer makes sense to have it structured that way. Breaking down all of the documentation into smaller, more manageable chunks, before deciding how best to piece them back together is the current focus.

Thankfully, in preparation for our move towards single source, we had already audited our content and so, if nothing else, I have all the discrete sections of each of the current documents already list in a ‘management friendly’ spreadsheet.

So, with a bit of manipulation I can easily mockup a sample set of information topics, and then figure out how best to present them to the audience, be it PDF, online help, or via the web.

Once we’ve got a good idea of our final deliverables, I’ll run them past a sample of the intended audience to make sure they are both what is required and to set the expectation of what we are, and aren’t, delivering. Hopefully, gaining buy-in to our plan as early as possible will mean the information we provided is better received and may even start further discusssions around future improvements.