Single source authoring

Single-source authoring is writing a topic or document so you can use these topics or documents in multiple results: print, online help, PDF, and ezines. Write a document, a single font, and use that document multiple times and places. It is the ultimate in recycling.

This article describes some necessary elements of single-source authoring and offers an overview of some of the possible pitfalls. I want to present authorship from a single source to those of you who have never heard of it, and perhaps give it a treat. If you are interested, you will find more information on the web and in various publications on single-source authorship. To start, I recommend the very complete book by Kurt Ament, Single sourcing: creating modular documentation from William Andrew Publishing Technical Writing Series.

The intention behind single-source authorship

First, I must clarify what I mean by single-source authorship. Actually I have two different meanings:

• Write the information for reuse, which means you can reuse it in the current document or in other documents or even other types of documents.

• Write using a publishing tool that allows you to convert your information to another format or many other formats: print, online help, PDF.

First, create a document, topic, paragraph, or even a sentence, and store the document, topic, paragraph, or phrase in a place where the information can be accessed by multiple authors for use in other documents. This is why, when you read about unique sourcing, you also see much more about topic-based authoring and content management systems (CMS). Obviously if you’re going to have text snippets floating around for multiple writers to access and use, you’d better be able to manage the snippets.

With few exceptions, I never worked on pieces smaller than a theme. Actually, if you are using a theme as its smallest level of granularity, you may not even need a CMS. You could probably use whatever font control you’re using right now or even a spreadsheet. However, a spreadsheet is not so manageable when you have multiple authors. In that case, you should be careful with document control, but it is possible.

What were the exceptions, you ask? In a place where 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 good thing about this is that if you have a Warning that you use throughout the document, you can write it once and then refer to it elsewhere. Now suppose you should review the warning. Instead of searching for and replacing this little gem, you just need to change it in 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 that we use the glossary term as the file name. Every time we add another term, naming the file for that term, it is automatically sorted alphabetically in the file list. Import the file list into a data map and you’re ready to go. Of course, in FrameMaker, you should be careful to check your list because it tends to rearrange things a bit.

Single-source authorship candidates

The first step, then, is to determine if your documents are candidates for a single provider. After all, this kind of change should not be taken lightly or by a weak heart. If it is not worth spending money on time and energy, you better not even try.

So how do you identify documents that are candidates for single-source authorship? The first thing to do is look for items that you can take advantage of in your portfolio:

• Do you output to more than one media type? In other words, do you create information for online help and then rewrite that information for a user guide? Don’t you find it useful to be able to write once for all these outputs?

• Do you have any information that appears on all or most of the documents? Many guides and manuals created for end users have the same main theme, but I often see the main theme rewritten, or worse, copied and pasted without any sense of document control. This can turn you around and bite you if you’re not careful.

• Do you write instructions for multiple products that use the same or a similar user interface?

• Do you have multiple products with similar functions that differ only in name or attribute?

• Do you have paragraphs or statements that you use repeatedly, such as warnings, cautions, or notes? You can keep a complete library of these snippets for use in many other places. Regulatory agencies love the consistency this brings to their documents.

Unique and theme-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. Building documents from unique themes is the ultimate in flexibility. Writers can access the folder containing the material stored in their document control system and begin assembling the materials necessary for their document. You can add identifiers and metadata to each topic for easy access by everyone.

This means that the first year of a single-source / theme-based authoring company won’t save you as much time or money as the following years. After all, the first year is the year that you are creating all of these reusable themes so that they are not saved in real time. However, in the following years, at the time you receive the assignment, you can immediately collect your static information, such as major topics or maintenance schedules, for an “annual review.” If reviewers already reviewed these topics this year, perhaps for another product, so much the better. While this review is in progress, begin writing the new information.

Oh, and translation, all you have to translate now is the delta, the changes between last year’s main theme and this year’s. I can almost guarantee that this is a better and more frequent review than the one you are receiving today. In the meantime, you’re busy looking for those themes that need updating or writing new themes for the new features. You don’t need to touch any topic that doesn’t need updating. Again, you have written once and reused when necessary.

Check my article Topic-based authoring, at EzineArticles for information on how to write topics.

Problems with single-source authoring

The biggest problem in single-source authoring is project communication. If you have a store for one or two people, communication is probably not a big problem. However, if your department has more writers or more locations, communication is paramount. The last thing you want to hear from a reviewer or evaluator is that you can see that the online help or the User Guide had multiple authors.

You also don’t want two people to write 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 problem is writing in a generic way. If you are used to including the name or version of the product, or any other identifier, get over it. You can use conditional text for product names, but if it’s not relevant to the topic, keep it generic. You can put all that information in one of the documents, like the Release Notes.

Generic writing extends to topic writing that you use both in online context help and in printed documents, including PDF formats. You may want to express things a little differently depending on the output medium. For example, when writing a topic for printing and online help, should you condition the first step of each procedure?

For example, when writing an online help procedure, a good practice is to start with navigation, as in “On the command bar, select window> menu item> function. “This is because you don’t know where the user is when you access the help topic: from a search? In the TOC? You don’t know.

Would a navigation step in a printed document where the procedure is one of a set of procedures in a section describing that particular window be required? Would that step be on the way or should I just ignore it as a problem? In my opinion, it is not a problem and you should ignore the redundancy that can occur. That is just an opinion and something you must decide before starting.

In another situation, what if the end user you are writing to access this topic on an electronic tablet or even on a smartphone? You may need to write conditional text that displays your text in one way for online help and in another way for the much smaller display area.

In conclusion

If you or your group of writers commit to creating single-source documentation for all of your results, do your homework, get in touch, make sure you have buy-in from all stakeholders, or it just won’t work. Trust me. I know.

If you poverty to bask the Nifty Beingness: Making money in the richness of your own domicile oeuvre online, then this is for YOU!: Click Here