Managing Documentation Sources

By Jayanthi Krishnan

Managing the documentation sources is one of the important tasks in the documentation process cycle. Some points that need to be considered for a good documentation management process are ease of use, accessibility, traceability, reusability, and modularity.

The practices that you can implement may vary depending on the type of the organization, the size of the documentation team, the company's willingness to invest on a good tool, and the importance of documentation within the organization.

Here are some tips that may still be useful in any kind of setup:

# 1. Developing a scalable process to manage the documentation sources

If you are a lone writer or your team is just formed, chances are that the process to manage the documentation sources may not be in place, or even if it is, it could be very rudimentary. At this stage, it is necessary to have a process for managing the sources such that if the team grows, the process for managing the sources is scalable. In the initial stages, you may resort to storing the sources on local servers. As a good practice, avoid relying on the manual process of archiving the documents. If you do use this process, make sure that data is managed and archived on servers that are backed up regularly and that the data can be easily retrieved from the backup media.

#2. Using professional archiving tools

Archive and manage source changes using one of the professional tools that are available. Choose an appropriate tool depending on cost, ease of use versus learning curve, setting-up time and effort, maintenance costs, and licensing.

Some of the widely used tools are ClearCase, CVS/WinCVS, and Visual SourceSafe. These are document management tools that enable you to get multiple traceable versions of the same file. CVS is a freeware that is far easier to use than ClearCase. These tools were primarily designed to handle text code. Now, these tools are used for creating source management systems. Some of the core benefits of these tools are as follows:

• Provides a systematic method for categorizing, storing, and retrieving documents
• Enables multiple traceable versions of the same file
• Facilitates storing of files with specific labels, which can later be retrieved by using the labels
• Improves and protects access to information
• Enables collaboration and merging, which means that two people can work on the same file at the same time without disrupting each other’s work
• Provides a central file repository that improves operational efficiencies
• Enables management of any type of file, text or binary

With such a setup in place, you can choose to archive the documentation at various stages of the documentation cycle using appropriate tags. These tags are useful if you want to retrieve a specific version at any point in time. Besides, most of these tools are also integrated with a defect-tracking tool, which is very useful in tracking the changes to the documentation sources.

#3 Single-sourcing the documentation sources

Single-sourcing is the practice of using documentation content repeatedly for a variety of purposes, thus reducing duplicated efforts. This is an excellent practice to implement as it provides an effective method for managing sources. Single-sourcing means that you would use a common source to produce multiple output formats, such as PDF, online help, and context-sensitive help. This is easier said than done as not all tools enable single sourcing. Tools such as Microsoft Word do not have any specific features to facilitate this. Single-sourcing can be very well managed using Adobe FrameMaker, with its features such as conditional text and text insets.

Single-sourcing can be done at three different levels - low, mid, and high. An example of a low-level single-sourcing solution is documentation for a product that is available on all platforms (Windows, all Unix flavors), but the actual differences between these are minimal. In this case, it is a wasted effort to maintain multiple platform-specific versions of the documentation. The best solution is to have a single source with appropriate text conditions for each platform. The PDFs can then be generated for each version from this single source. Mid-level single-sourcing involves generating the online help and context-sensitive help in different formats (html, winhelp, javahelp) from the same source. High-level single sourcing requires the implementation of a complete single-sourcing content management system, which can be facilitated by using one of the content management tools. More on this is covered in point 5.
I have reverted back to the original sentence in the para above as two statements starting with “In this case” does not read well.

The conditional text feature in FrameMaker enables you to preserve the entire content that needs to be shared across different versions of the document, within the same document by showing or hiding the content appropriately. You can create multiple conditional tags based on various requirements and use the FrameScripts to automate some of the repetitive tasks based on the conditional texts used in the documents.

The text inset feature in FrameMaker enables you to maintain a single copy of the module that needs to be used at multiple locations, as an inset. These insets can then be imported wherever required. If there are large documents with many modules that are repeated then you can choose to create an inset for these modules and import them at all the required locations. The content within the insets can also be conditionalized. Changes need to be done only in the source inset and these changes get reflected at all places. This also facilitates better management and sharing of content.

The benefits of using single-sourcing are as follows:

1. Eliminates the cumbersome process of having to manually revise each instance of the same content; in effect reduces the human error factor.
2. Saves you significant amount of time since you do not need to perform similar set of tasks repetitively.
3. Eases the task of managing sources since only a single source is used for multiple outputs, thus enabling uniform look and feel across output formats.
4. Reduces costs and improves efficiency through the use of organized content.

#4. Managing document source changes using a defect tracking system

Organizations with reasonably good processes ensure that all changes to the code sources are recorded in the defect tracking system. This is useful as it provides good reference information and facilitates an easy method of communicating the information to the entire team. Similarly, you can ensure that any change to documentation is handled through the defect tracking system.

The benefits are as follows:

• Documentation changes are visible and available for all to see and comment on.
• Easy to track various issues.
• Easy to gather documentation metrics, which can be used to generate various reports. For example, engineering updates would be measured by the number of bugs fixed for a project. Documentation changes can also be tracked in the same manner.

#5. Planning usage of graphics in documents

Put some thought into the graphics that need to be included in the documents. Try to evolve a process such that the sources have images only if they are absolutely necessary, but do not overload the documents. Common images should be shared. Although it is true that a picture can say a thousand words, it is also true that graphics add to document size and localization costs. Optimize the usage of graphics and follow the practice of sharing or cross-referencing the images wherever possible. If it is feasible, create a common pool, something like a single-source for images from where the images can be used and changed, as required.

#6. Reducing localization costs

We write for a global audience and localization is an important point to consider. Localization costs are based on various factors such as number of pages, words, images, difference in content from earlier releases, and possibility of effective reuse of translated content. Having a good documentation management system in place facilitates the translation process by making the sources available at a single location. A single-sourced? system ensures that unnecessary repetitions are avoided, thus resulting in reduced translation costs and turnaround time.

#7. Setting up a content management system

A good content management system (CMS) can reduce the cumbersome task of maintaining and tracking the changes to repetitive content. The CMS has its own centralized database and content can be stored, shared, and repurposed for different requirements, on different media. Any change to content will need to be implemented only in the source and the consecutive instances will automatically be updated. If required. you can revert back to any specific version of the document.

Some of the benefits of using a content management system are as follows:

• Improved productivity and document accuracy
• Efficient reuse and repurpose of content
• Effective linking between the content
• Traceability and automation
• Enhanced Document and content security
• Reduced localization costs

Irrespective of the method you choose, it is necessary to have a good content management system in place. This eases the task of managing the changes to sources, ensures that content is easily available, and improves content accuracy. This can be implemented by using a professional tool to track check-in and check-out of documents. Link the document update process with a defect tracking tool. Consider graphics that need to be used and the impact of localization on documentation changes.

Jayanthi Krishnan is a Technical Writer with Symantec Software, Pune.

To contribute to this column, contact the column editor, Ramesh Aiyyangar.