Latest posts by techwriter (see all)
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
- An Amazing and FREE Source of Magazines and Periodicals — ISSUU - November 25, 2016
Single-source authoring is writing a topic or document so that you can use these topics or documents in multiple outputs: print, online help, PDF, and e-pubs. Write a document, a single source, and use that document multiple times and places. It is the ultimate in recycling.
This article outlines some necessary elements of single-source authoring and offers a view of some of the possible pitfalls. I want to introduce single-source authoring to those of you who have never heard of it and, maybe, give you a taste for it. If you do find yourself interested, you find more information on the web and in various publications about single source authoring. To get you started, I recommend Kurt Ament’s very comprehensive book, Single Sourcing: Building Modular Documentation from William Andrew Publishing Technical Writing Series.
The intention behind single-source authoring
First, I must clarify what I mean by single-source authoring. Actually, I have two different meanings:
- Writing the information for re-use, meaning you can re-use it in the current document or in other documents or even other types of documents.
- Writing using a publishing tool that allows you to convert your information to another format or many other formats: print, online help, PDF.
In the first instance, you create a document, topic, paragraph, or even a phrase and store the document, topic, paragraph, or phrase in a place where multiple authors can access the information for use in other documents. This is why, when you read about single sourcing, you also see a lot of blather about topic-based authoring and Content Management Systems (CMS). Obviously, if you are going to have bits and pieces of text floating around for multiple writers to access and use, you had better be able to manage the pieces.
With few exceptions, I never worked in pieces smaller than a topic. Actually, if you are using a topic as your smallest level of granularity, you may not even need a CMS. You could probably use whatever source control you are now using or even a spreadsheet. However, a spreadsheet is not as manageable when you have multiple authors. In that case, you have to be careful about document control but it is possible.
What were the exceptions, you ask? At one place I worked, we created a library of Warnings, Cautions, and Notes. Some of these bits appeared repeatedly in many different documents, some only once. The beauty of this is that, if you have a Warning that you use throughout a document, you can write it once and then reference it in all other places. Now, let’s say that you have to revise the warning. Rather than doing a find and replace for this little gem, you only have to change it in the one place and it changes in every document you open that references that Warning.
The other exception is a glossary. The only time I did this, we were using DITA. The beauty of using DITA was we used the glossary term as the name of the file. Every time we added another term, naming the file for that term, it automatically sorted itself alphabetically in the list of files. Import the file list into a ditamap and you are good to go. Of course, in FrameMaker, you have to be careful to check your list because it tends to reorder things a bit.
Candidates for single-source authoring
The first step, then, is to determine if your documents are candidates for single sourcing. After all, this sort of change should not be taken lightly or by the faint of heart. If the bang isn’t worth the buck spent in time and energy, best you not even try it.
So how do you identify documents that are candidates for single-source authoring? The first thing to do is look for items you can leverage throughout your portfolio:
- Do you output to more than one type of medium? In other words, do you create information for online help and then rewrite that information for a user’s guide. Wouldn’t you find it useful to be able to write one-time for all of these outputs?
- Do you have some information that appears in all or most documents? Many Guides and Manuals created for end users have the same front matter yet I frequently see that front matter rewritten or, even worse, copied and pasted with no sense of document control. This can turn around and bite you if you are not careful.
- Do you write instructions for multiple products that use the same or similar user interface?
- Do you have multiple products with similar functions that differ only in name or attribute?
- Do you have a paragraphs or statements you use repeatedly, such as Warnings, Cautions, or Notes? You could keep a whole library of these snippets for use in many other places. Regulatory agencies love the consistency this brings to your documents.
Single-source and topic-based authoring
Good writing practice links topic-based authoring to single-source authoring because it is easier and more efficient to create a topic and use it in as many documents as necessary. Constructing documents from single topics is the ultimate in flexibility. Writers can access the folder containing the front matter stored in your document control system and start assembling the front matter pieces necessary for their document. You can add identifiers and metadata to each topic to make it readily accessible to all.
This means that the first year of a single-source/topic-based authoring venture will not save you as much as time or money as succeeding years. After all, the first year is the year you are creating all these reusable topics so no real time saved. However, in succeeding years the minute you get the assignment, you can immediately assemble your static information, like front matter or maintenance lists, out for an “annual review.” If reviewers already reviewed these topics this year, perhaps for another product, so much the better. While that review is happening, you start writing the new information.
Oh, and translation, all you have to translate now is the delta, the changes between last year’s front matter and this year’s. I can almost guarantee this is a better and more frequent review than your front matter is getting today. Meanwhile, you are busily finding those topics that need updating or writing new topics for the new features. You do not need to touch any topic that doesn’t need updating. Again, you have written once and re-used at need.
Refer to my article Topic-based Authoring, in EzineArticles for information about writing topics.
Issues with single-source authoring
The biggest issue in single-source authoring is project communication. If you are a one or two person shop, communication is probably not much of an issue. However, if your department has more writers or more locations, communication is paramount. The last thing you want to hear from a reviewer or tester is that they can see that the online help or User’s Guide had multiple authors.
You also do not want two people writing the same topic. If you think it is enough to divide the areas you are documenting and assign those areas to different writers, think again. It is not unusual, especially when documenting a software application, that a particular function is available from two different windows. Therefore, communication is paramount.
The second issue is writing generically. If you are accustomed to including the product name or version, or any other identifiers, get over it. You could use conditional text for product names but if it is not important to the topic just keep it generic. You can put all that information in one-of documents like Release Notes.
Writing generically extends to writing topics that you use in both online context-sensitive help and print documents, including PDF formats. You may want to phrase things somewhat differently depending on the output medium. For example, when writing a topic for print and online help, should you conditionalize the first step of each procedure?
For example, when writing an online help procedure, a good practice is to begin with navigation, as in, “On the command bar, select window > menu item > function.” This is because you do not know where the user is when they access the help topic: from a search? On the TOC? You do not know.
Would a navigation step be necessary in a print document where the procedure is one of a set of procedures in a section describing that particular window? Would that step be in the way or should you just ignore it as a non-issue? In my view, it is not a problem and you should ignore the redundancy that may occur. That is just an opinion and something that you should decide before you start.
In another situation, what if the end user your are writing for accesses this topic on an electronic tablet or even a smart phone? You may have to write conditional text that displays your text one way for online help and another way for the much smaller display area.
If you or your group of writers is committed to creating single-source documentation for all your outputs, do your homework, communicate, make certain you have buy-in from all the concerned parties or it simply will not work. Trust me. I know.
I love technical writing. Finding new and better ways of writing is a passion of mine. At The Technical Author, I try to provide useful tools for perfecting our craft. The Book Recommendations page contains a list of technical writing books to educate and guide writers interested in perfecting their craft.