Hello! My name is Elena Tolmachyova. In the company "DoksVizhn" I am engaged in the development of user documentation.

Recently, to create various kinds of manuals for the operation of complex software systems, it has become increasingly popular to use the technology of a single source, which involves reusing any texts or images in a set of documents. Not so long ago, we began to use this technology to develop references and printed documents of DocVision, and in this article I want to share my experience.

Why did we choose a single source technology?

Those familiar with the company “DoksVizhn”, it is known that the main product developed by us is the platform Docsvision, and in addition to it there are many additional applications and modules. Since the auxiliary products are intended for use as part of the platform, when describing user actions in the documentation, we had to duplicate part of the text: either completely or with minor changes. This approach (taking into account the regular release of new versions for all products) was very laborious for technical writers, since The enormous amount of descriptions that were available did not allow us to track changes in all the repeating sections and promptly make changes to many documents at once.
')
There were other difficulties:

• The editor in which the development was carried out did not imply the simultaneous work with the document of several technicians, which made it difficult to organize team work on the project.
• Customers contacted the company with requests to provide documents in different formats: some preferred references, others needed the ability to edit text or print. We had no such opportunity.
• We also wanted all the documents produced to look in the same style. But due to the human factor, we could not do it at all: the provided template of the document allowed us to make changes, and it was regularly changed by someone at his own discretion, which spoiled the general impression of the company's documents.

At the moment when the number of minuses overflowed the cup of our patience, it was decided to radically change the way we develop documents. As a result, we chose a single source technology, and specifically we decided to use the DITA architecture in our work.

Why DITA

We liked DITA technology for several reasons. This architecture was developed specifically for technical writers, and many of the needs of documentation creators were already taken into account. For us, the determining factors were the following:

• the possibility of issuing documents in different formats (PDF, HTML5 and XHTML, Eclipse Help, TocJS, HTML Help, Java Help, OD, RTF, troff),
• rigid structuring of sections due to typed “topics” (concept, task, reference, etc.)
• possibility of simultaneous work on the project of several employees.

We chose the technology and began to draw up a plan for its implementation.

Planning

At the beginning of the journey, we drew up a plan that, of course, had to be corrected along the way. Here I present a set of stages in a strict sequence of execution, which (in our opinion) is optimal for solving the problem. I draw your attention to the fact that the plan will be suitable when switching to any single source technology (not just the DITA chosen by us).

The stages of our plan are:
1. Tools
2. Standardization
3. Design
4. Customization
5. Storage
6. Training

Below I will describe in detail all these stages. And let's remember those professionals who can assist with the implementation. When moving to a new system, we needed:
• Designer - helped prepare design layouts for documents
• Programmer - set up a tool to build a document in several formats
A coordinated all these works technical writer.

Instruments

New technology involves the use of new software, so in the first stage of implementation will need to select and purchase some software. At a minimum, you will need:
• editor for technical writers (we chose Oxygen XML Author)
• a tool for assembling documents from the original to the final format (we chose the DITA Open Toolkit to convert XML files to the supplied pdf and xhtml formats)
• storage system for source files and final documents (we chose TFS)

When choosing an editor, you should rely on the convenience of its use, the availability of functions to perform the tasks you need and, of course, the cost of the professional version. I note that support for working with DITA is implemented in almost all of the most popular editors for technical writers (Oxygen XML Editor, XML Mind, DocBook, AuthorIt).

Choosing a tool to assemble a document may not be necessary if the acquired editor allows you to assemble the document in the format and format required for the release. By design in this case, I mean the standard adopted in your company: fonts, logos, color schemes, format of final documents, etc.

The storage system can be used the same, which the developers in your company use to store the program code - in this case, you can save on the acquisition. It will only be necessary to come up with a good way to organize the storage, which I will discuss below.

Standardization

At the second stage of implementation, standardization of documents will be required. First of all, in order to achieve uniformity of the documentation structure, as well as in order to form a design task for the designer.

What will need to standardize:
• types of documents that will be issued for each of the company's products (user manual, administrator's manual, etc.)
• document structure for each of the allowable types (title page, introduction, chapters, sections, list of documents, annexes)
• composition of elements for each structure element (for example, for a title page: logo, product name, system name, version, document type)
• list of summary formats (pdf, odt, xhtml, etc.)
• list of localizations (Russian, English, etc.)
• method of numbering product versions and versions of released product documents

Let me explain why such a rigid standard is needed. As an example, consider the title page of the Docsvision documentation, which in the help and the printed format, although it looks in the same style, differs in the composition of the elements and the design method. For example, the help will contain a description of the purpose of the document (which is not printed on the title page, but in the Introduction section), the search field and the table of contents. Please note that the rest of the text of these sheets is the same, determined by the standard and does not depend on the style.


Fig. 1. An example of the composition of the elements of the title page

Creating a standard is perhaps the most important stage of implementation, because standardization errors will then smoothly flow into design layouts, and from there into a program for assembling final documents. If there are a lot of mistakes, all the work will have to start over.

Design

At the design stage, it is necessary to prepare graphic layouts of documentation, so that at the stage of setting up the tool for document assembly, the programmer has a clear understanding of how the help web page or a sheet of printed format should look.

It is advisable to familiarize the designer with the Style Guide used in the company in advance, and if he doesn’t have one (it happens often), then at least with the company's website.

Layouts need to prepare:
• for each of the previously standardized formats of final documents, for example, a separate set of pictures for pdf and a separate set of pictures for xhtml help
• for each of their standardized styling options (for example, if, according to the company's style, different colors are used for the products)
• for each of the standardized languages ​​(different terminology will be used in foreign languages, the programmer may not know, for example, the translation of the word “Search” into French)

Prepared layouts should be coordinated with the management of the company and after that you can proceed to the configuration step.

Customization

As I have already warned, you may have to connect programmers of various specializations to complete the setup. For the assembly of certificates requires knowledge of CSS, and the best will be the involvement of a specialist in the layout. And to set up output to print formats, only layout may not be enough. For example, to set up the Dita Open Toolkit tool we use, we needed a specialist familiar with XSLT transformations to build in PDF.

I don't know which programmers you need. But in any case, the following important factors should be considered:
• how many formats will the finished program collect from the source files provided by the technical writer
• how many styling options can be collected by one program or will require several programs for different styles
• how many languages ​​the program will support, and whether it will be possible to change the output language with a simple setting

An example of how to determine the number of means of assembling documentation is shown in the figure.


Fig. 2. Options for setting up the program for the assembly of documentation

When calculating the time allotted for programming, keep in mind that often this process is delayed for more than one month. While working, the documentator may need new tables, headings, and so on, and then the program will have to be updated.

Storage

The technology of a single source implies that the source files of the document (created by technical writers) and finished documents (created by the program for assembling a document) are different files. And these files must also be stored separately. Optimal use of the same version storage system as the developers of the software code of your company.


Fig. 3. The principle of storing files in a single source technology

The structure for storing source files should be based on the following principle:
• file storage for all technical writers should be the same,
• document titles should be standardized,
• versions of the documents produced should not intersect,
• Help collected automatically with the program code should be stored in the same place as the code.

The storage structure of the final documents should include:
• separate storage of different versions;
• within the version:
- separate storage for different formats;
- separate storage for different locations.

Training

At the final stage of implementation, you will need to train your colleagues to work with the new technology.

First of all, technical writers will need to learn a new editor for writing text.
Probably, you will also need to examine the list of tags that will be processed by the program for assembling documentation. For example, in DocVision, we use the DITA specification tags .
If a part of the text was copied before using the single source technology, now it can and must be learned to use it again. Plus, colleagues need to be familiarized with the new data storage structures and carefully ensure that this standard is respected by all.

What is the result

If the implementation is successful, the quality of the developed documentation will significantly increase, and the cost of its production will decrease. Technical writers will get more pleasure from their work, and their leaders will receive positive feedback from partners.

In conclusion, I will say that, on average, the introduction of a single source technology takes about six months, and the transfer of previously developed documents to the new format will take as much time.

For your information: many DITA materials are collected on the DITA Writer website, and there is also a list of references .

I hope this material will be useful for you and will help you to switch to a new technology quickly and painlessly!