The Big Picture

Deliverables are dead. Long live multi-format, anytime, anywhere delivery of information!

The more I think about it, the more I am beginning to see that creating content, writing and styling and planning, for “print” is no longer valid.

Quick caveat: Know your audience and the requirements. Many places mandate printed documentation in one format or another. I am purely talking about my own experience in a software environment.

I’m the first to admit that whenever I start thinking about updating a manual I think in print terms. I think of entire chapters of information, I think of how the user will be able to navigate and understand the layout and construction of the document. Changing those habits is proving hard but I’m slowly getting there.

Part of that change has come about by focussing on the information types we are going to be using as the building blocks of our single source system. Making each topic unique and complete within itself requires some thought and planning, and with that planning being focused on tasks, you soon get a simple outline of the required documentation including the type of information that you’ll be writing for each chunk.

As that realisation begins to sink in, the possibilities of re-use suddenly make themselves clear. It becomes a simple matter of drag and drop to create an entirely new manual, and a new delivery method becomes a simple matter of publishing to a new format.

The latter fits nicely with some current thoughts around how we get our technical information to our customers. Whilst I don’t think Author-IT would be the best solution, or at least the complete solution, I can see us focussing more on a web-based delivery of information, pulling other available content (from mailing lists and wiki pages) into an MSDN-like community website. Add in a blog and some interaction and it could very well be the shape of things to come.

As I’ve mentioned before, for a lot of people in the software industry, the internet is THE source of information. So rather than try and force how we want the information to be delivered (maintaining legacy documentation) I’m looking at how we can deliver something our customers will use, without succumbing to the Web 2.0 crazies. Yes it could have a blog, but does it need one? Yes we could use Twitter to provide ‘from the floor’ thoughts from the development group but who would sanitise them first!

Wikifying the doc set (to borrow a phrase) is a possibility of course, but that would only be part of this solution, and would have to include the ability to package it up as a different deliverable (PDF for example) so the information can be accessed when the internet isn’t available, a requirement of our documentation.

There are other considerations of course, all of which are still being thought through and will need discussion and buy-in.

Exciting times ahead I think. More on this as it develops.

Written By

Long time blogger, Father of Jack, geek of many things, random photographer and writer of nonsense.

Doing my best to find a balance.

More From Author

You May Also Like

Reasons to work

Hotel Life

Everything changes


I’m at a similar point, and I’m lucky to be working in a place where I’ve been able to make that argument and be told, “Make it happen.” We’re trying to shift over from a point-publishing model to a state of constant information flow. Information comes in from all over, gets processed into usable knowledge by us tech writers (we’re still called that), and gets posted into the right places as soon as it’s ready. No deadlines, no releases, just constant incremental additional value. It’s pretty fun, actually.

Kat says:

This sounds really exciting! Give us more news….

Marcus says:

That was interesting to read. I’m currently switching from writing book-centric documentation to DITA and find it diffcult at times to keep that old book/chapter thinking out of my head…

As for “Deliverables are dead”; we recently conducted a survey amongst our main audience and asked them which format and presentation type they like best for the documentation (we have PDF, HTML with Java or JavaScript navigation, JavaHelp and CHMs) and about 90% of them voted for the good old PDFs.

With that in mind we decided to continue using FrameMaker, because of its excellent PDF output, although it’s probably not the best tool for DITA.

Good on you Marcus, always deliver what the audience want!

Tanja says:

I hear you. Lately, I have been thinking about similar issues myself. What to do when talking about “deliverables” is not enough anymore?

If a team defines itself via its deliverables, it risks being forever labeled “the team that does user guides” or “the team that does helps”. Even worse, the team risks limiting itself by the print guide thinking you descibed. Even when they would be or could be doing so much more. It can be safer, and more accurate, to explain that you are creating content that is used in various ways.

What are those various ways then? There are so many aspects to consider.

– Tangible deliverables. Some of the content you create still gets compiled into printed user guides, PDF files for the web site, a help file, or something else that you can still call a deliverable.
– But what is the rest? Just content, compiled together based on topics or content types, for example. If your content appears here and there everywhere on a web site, you cannot necessarily call that a deliverable in the traditional sense. It is also possible to produce separate content types, such as tips, shortcuts, or Q&As that can be used in multiple ways.
– Publishing channel: Web, mobile, help…
– Publishing format: PDF, HTML, XML, any help file format…

I’m trying to eventually find a short and snappy way of describing all this ๐Ÿ™‚

Comments are closed.