Now we have our client, our table of contents that tells us what we'll be writing, and our meta-documents that tell us how we'll be writing it. So we're ready to actually write the thing, yes?

Well, yes and no. Now, your next step depends on what software you're using. If you're writing this whole thing monolithically in Microsoft Word or Open Office without the aid of VB-scripting, then yes - have at it. If, however, you're following the industry development into topic-based content and single-sourcing, then no.

The term 'single-sourcing' is (ironically, for an industry that prides itself on consistency) used to denote two rather different concepts. In my opinion, they're not that different - in fact, one is just the logical extension of the other, but it they seem to be taking their time to proliferate through to professional practise.

Single-sourcing is what it says on the tin - creating multiple outputs (eg the same user manual in PDF, webHelp and OracleHelp, in different languages, and including or excluding different features) from the one lot of text. You write the document once, and then you can produce it a myriad of different ways. It's obvious - I hope - why that's a good thing. Instead of having to reformat HTML and OracleHelp manually, it's done for you. If a feature needs updating, you update it in one place, without having to hunt though fifteen versions of the document to make the same change.

This kind of single-sourcing is well-established in the industry now, thanks to players like Author-it and Robohelp. Provided you've set up your environment correctly, you can often create the document with little thought to the finished format - the software will take care of that for you.  The other kind - the extension of that - is sadly less well-integrated, because it does require you to think things through first.

Single-sourcing your source

It's not much of a progression, I think, from considering using one point of source for multiple documents, to considering using one point of source for multiple parts of that source. For example: the software you're documenting has a screen that's a little complex to get to, and handles a lot of tasks. Each of those tasks will be a separate topic, which means you'll be telling the user how to get to this screen a dozen times or more.

If that task changes - say, the developers realise that the screen's really too hard to get to, and simplify the interface - you now have to go through and change that a dozen times, and triple-check that you didn't miss any of them. Say they do this to a whole lot of screens. Now you have hundreds of topics that you need to make miniscule changes to. Sounding familiar yet?

It's just like the multiple-document problem - having to make the same change over and over again through your work. The only difference is we're talking about your source document instead of your final output. Can you guess the answer?

Reusing content. Most decent authoring programs support it, to some degree. You create the 'how to get here' section once, and then you embed that piece into all the topics that need it. The embedded sections link back to the original, so if the original changes, so does everything else. Now, when the developers make that change, you edit one file and the change propegates through the whole document. You've just reduced your maintenance workload by 95%.

The difficulty of single-sourced-source

The problem in the industry is that this concept is dependant on tools that are still very new - most technical writers are still developing in Microsoft Word, armed with an armada of VB scripts. And that leads to the fact that most technical writers don't think in a single-sourced-source way. They write what each topic needs, instead of considering ways this particular section could be generalised without losing clarity, and therefore reused elsewhere. When updating documents originally written by someone else, I continually come across sections where identical text has been copied or rewritten rather than single-sourced - and it's usually when I'm having to update that text.

It takes a switch in mindset, and it's much easier to do before you start than as you're going- though you will inevitable end up converting sections into single-source as you discover ones you hadn't predicted.

Planning single-sourced-source

Before you get stuck into writing your document, take a good look at your notes, and the content. Look for any areas of common ground - tasks that use the same procedures, topics that need very similar descriptions. Don't worry if they're tiny - even if they're only two steps long, if they're identical, they should probably be single-sourced. Make a separate list of all these common things. 

I find it better to write the single-sourced-source first, before the rest of the document, for three reasons:

1. It helps me to find more content areas to single-source, because I'm focussed on doing that, rather than on writing a specific topic or procedure.
2. It helps me to keep the single-sourced sections general enough that I can use them everywhere I have to.
3. The actual document writing goes much faster, because a lot it is now just plugging in content I've already written.

It will take some adjusting to consider your document from a single-source perspective, but I garuantee the effort will pay off in efficiency, consistency, and a much better finished document set.

• Add New
• Search
• RSS

Comments (0)

Write comment

Your Contact Details:

Name:

Email: do not notifynotify

Website:

Comment:

Title:

Message:

Security

Please input the anti-spam code that you can read in the image.

Powered by !JoomlaComment 4.0 beta2