The success of a move to topic-based authoring and/or structured writing depends on the order of your steps – and good planning is key. You can’t make it up as you go along.
The Company I Work For is moving its extensive user documentation to topic-based authoring and a DITA-compliant information model. That requires converting existing documentation, such as user manuals.
Many current manuals are like tutorials: They guide readers by example with lots of screenshots. They are easy to follow along, but more difficult when you need to know about individual procedures or about scenarios which don’t match the example.
I’m currently converting and restructuring some of these user manuals into topics. Basically, I’m taking them apart and reconstructing them into concept topics, procedure topics and reference information.
Here are some lessons we learned in the process:
1. Define the structure first.
Even if it takes a week or two, be sure you have 80, 90% of your structure in place before you start tearing up contents to convert them. If you simply make it up as you go along, you’ll get an abstraction of whatever content you start with – which most likely won’t suit all of your contents.
You’ll be better off, if you at least sketch out the common topic types such as concepts, procedures and reference and define what goes into them in which order.
For example, procedure topics could contain
- One or two intro/context paragraphs
- Prerequisites (if any)
- Procedure as a list of numbered steps
- Expected results
- Exception handling (if possible and applicable)
2. Carefully select pilot projects.
Start by converting content that is both typical and mainstream. This way, you can validate your structure and discover gaps or errors.
This also makes it easier to show progress and reap some quick wins. You can give managers and colleagues something tangible what the future documentation will look like to ensure confidence and support on your path.
3. Draft the new topic structure.
Use the defined structure to draft a specific structure for the content you’re about to convert. Just leafing through the pages of a manual will give you a pretty good idea which topics you will be able to create from it.
Order all those topics into a structure, so you have sort of a table of contents for the new topic-based manual before you begin. This structure need not be set in stone, if you find you need to arrange or add topics, but it should present a sensible picture.
Ensure, for example, that procedural topics are backed up sufficiently by concept topics so we have room to explain the “what” before you explain the “how-to”. Or, if you have both setup procedures and operational procedures, ensure that setup corresponds to operations.
4. Proceed along the old content.
In the actual conversion process of chunking text, moving it into the new structure and rewriting it, follow along the old structure. That will create a temporary mess in your new structure where you may find yourself dumping random paragraphs and sentences under headings.
But this allows you to cross off section by section in the old manual with the confidence that you have moved it over. This is much faster and more reliable than constantly going back to the old manual, worrying if you’ve left anything behind.
Your turn
Do you find these tactics helpful? What experiences have you had when converting legacy content into structured documentation? Feel free to leave a comment.
Filed under: DITA, structured writing, topic-based authoring |
Kai's Tech Writing Blog 
This is a good article, Kai, but I think you’re being very optimistic to say that it only takes one or two weeks to develop the model structures for your new topics. I think it could take much longer.
Converting legacy content is also an opportunity to be a ruthless editor, and to abandon anything that isn’t going to be useful to your users. I’m thinking about all that “thank you for buying our product” stuff that Marketing made you add at the start of the printed user guide. That’s a “topic” that no-one is ever going to read!
You can also be sensible about lots of engineering details that don’t help users do their jobs. That’s the sort of stuff that Reference topics were invented for.
Thanks, David, for your comment. You’re right, developing the structure can take much longer. Come to think of it, my 1-2 weeks estimate works if (a) you have a pretty good picture of the legacy content and (b) you’ve developed model structures before. Else it most likely will take longer.
Yes, the conversion is about the best opportunity you’ll get to lose unwanted, obsolete or unnecessary content. And a good opportunity to discover stakeholders you never knew you had until they complain about what’s now missing. 🙂
Indeed, I’m finding that a lot of stuff that was in generic, less than well-designed topics is moving into reference topics…
IMHO, instead of
“For example, procedure topics could contain:
– One or two intro/context paragraphs”
think of
(a) ShortDescription (short and effective, see DITA authoring rules)
(b) minimalism (give the end user a chance to THINK and ACT)
Thanks, Marie-Louise,
your reply (and David’s too) indicate how diverse tactics can be, depending on the legacy content and the documentation strategy as a whole. I agree, a minimalist approach with only a short description is definitely a viable option.
In our particular case of an asset management system, however, we need be quite explicit and tell users which procedures apply to which instrument types and sub-types, which markets and which accounting standards. It’s not an area where we can simply empower users to think and figure it out on their own… 🙂
[…] Have a tactical framework. Ensure you know the documentation structure you aim for and how you will get there in a project. Consider for example the Top 4 tactics to structure legacy documentation. […]