I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here.
Why? – why single source?
A quick summary of our current situation. We currently maintain (and add to) ~2000 pages of documentation. The same content is used for both the PDF manuals and the online help provided with the product (exactly the same, no restructuring). There are various levels of coverage (some good, some bad), we are embedded within an Agile development environment, limited publications resource. On top of that we have an aggressive release schedule and a two-tier product which includes a development kit and an application built by us using that development kit.
Whilst we have made good strides in improving how we work with the software developers – we have a technical writer embedded in each new feature team and the benefits are evident from both sides – we know we need to be focussing our efforts in the correct areas, and providing information in a structure and format that meets the needs of our audience. Luckily we have direct access to the largest section of the audience as they work for the company.
Better structured information is one of the requests, and to allow us to get the most of our current documentation we would need to reuse a lot of the content we have already, but it’s locked away in FrameMaker files, sometimes in the depths of a 100 page long chapter. What to do?
Ultimately we believe that the ability to reuse our content will make producing the content faster – the current documentation set is unwieldy and hard to search, a little digging reveals some duplication already exists – and make us much more flexible when it comes to providing useful sets of information for our audience/customer.
Eagle-eyed readers will have spotted that we already single source our documentation and online help from the same FrameMaker files, but as we don’t reconstruct the online help into something more intuitive and useful it is, essentially, an HTML rendition of the manual. Not ideal by any stretch of the imagination.