February 18, 2015 at 14:56Implementing DITA Single Source Technology in a Software Development Company
Hello! My name is Elena Tolmacheva. At DoxVision, I am developing user documentation.
Recently, to create all sorts of manuals for the operation of complex software systems, the use of a single source technology, which involves the reuse of any texts or images in the developed set of documents, has become increasingly popular. Not so long ago, we began to use this technology for the development of references and printed documents of DoksVision, and in this article I want to share my experience.
Those who are familiar with DoksVision company know that the main product we are developing is the Docsvision platform, and in addition to it, many additional applications and modules are released. Since 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 in full or with minor changes. This approach (given the regular release of new versions for all products) was very laborious for technical writers, as the vast amount of descriptions available did not allow us to track changes in all repeating sections and quickly make changes to many documents at once.
There were other difficulties:
• The editor in which the development was carried out did not imply several technical writers working with the document at the same time, which made it difficult to organize team work on the project.
• Customers contacted the company with requests for documents in different formats: some preferred information, others needed the ability to edit text or print. We did not have such an opportunity.
• We also wanted all issued documents to look in the same style. But due to the human factor, we could not achieve this in any way: the provided document template allowed us to make changes, and someone regularly changed it at our discretion, which spoiled the general impression of the company's documents.
At a time when the number of minuses overwhelmed our patience, it was decided to radically change the way documents are developed. As a result, we opted for single source technology, and specifically, we decided to use the DITA architecture in our work .
We liked DITA technology for several reasons. This architecture was developed specifically for technical writers, and many of the needs of documentation creators have already been taken into account. The decisive factors for us were the following:
• the ability to issue documents in different formats (PDF, HTML5 and XHTML, Eclipse Help, TocJS, HTML Help, Java Help, ODE, RTF, troff),
• hard structure of sections due to typed "topics" ( concept, task, reference, etc.)
• the ability to simultaneously work on a project for several employees.
We selected the technology and began to draw up a plan for its implementation.
At the beginning of the journey, we made a plan, which, of course, had to be adjusted. Here I give a set of stages in a strict sequence of execution, which (in our opinion) is optimal for solving the task. I draw your attention to the fact that the plan is suitable for the transition to any single source technology (not only the DITA that we have chosen).
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 recall those specialists who can assist with the implementation. Upon transition to the new system, we needed:
• Designer - helped prepare design layouts for documents
• Programmer - set up a tool for assembling a document in several formats.
A technical writer coordinated all these works.
New technology implies the use of new software tools, so at the first stage of implementation, you will need to select and purchase some software. At a minimum, you will need:
• an editor for technical writers (we selected the Oxygen XML Author)
• a tool for assembling documents from the source format to the final one (we selected the DITA Open Toolkit to convert XML files to the supplied pdf and xhtml formats)
• storage system for source files and resulting 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 a professional version. I note that support for working with DITA is implemented in almost all the most popular editors for technical writers (Oxygen XML Editor, XML Mind, DocBook, AuthorIt).
The choice of a tool for assembling a document may not be necessary if the acquired editor allows you to assemble a document in the format and format required for release. By design in this case, I mean the standard adopted by your company: fonts, logos, color design, format of final documents, etc.
The storage system can be used the same one that the developers in your company use to store the program code - in this case, you can save on the purchase. You only need to come up with a good way to organize the repository, which I will discuss below.
At the second stage of implementation, standardization of documents will be required. First of all, in order to achieve uniformity in the structure of the documentation, and also so that it would be possible to formulate a task for the designer to style.
What will need to be standardized:
• 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 acceptable types (title page, introduction, chapters, sections, list of documents, applications)
• composition elements for each element of the structure (for example, for the title page: logo, product name, system name, version, document type)
• list of final formats (pdf, odt, xhtml, etc.)
• list of localizations (Russian, English, etc.)
• method of numbering product versions and versions of issued documents for the product I will
explain why such a strict standard is needed. As an example, consider the front page of the Docsvision documentation, which in the help and in the printed format, although it looks in the same style, differs in the composition of the elements and the way they are designed. For example, in the help there will be a description of the purpose of the document (which is in printed format not on the title page, but in the "Introduction" section), a search field and a table of contents. Please note that the rest of the text of these sheets is completely the same, is defined 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 then flow smoothly into the design layouts, and from there - into the program for assembling the final documents. If there are many mistakes, all work will have to be started anew.
At the design stage, it is necessary to prepare graphic layouts of the documentation so that at the stage of setting up the tool for assembling the document, the programmer had a clear understanding of how the help web page or a printed sheet should look.
It is advisable to familiarize the designer in advance with the Style Guide used in the company, and if suddenly he is not (this happens often), then at least with the company's website.
Layouts need to be prepared:
• for each of the previously standardized formats of final documents, for example, a separate set of images for pdf and a separate set of images for xhtml-help
• for each of their standardized styles (for example, if different products are used in accordance with the company’s style color spectrum)
• 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 agreed with the company’s management and then you can proceed to the setup stage.
As I have already warned, you will probably need to connect programmers of various specializations to complete the setup. Building certificates requires knowledge of CSS, and the best way is to have a layout specialist. And to set up output in print formats, only typesetting may not be enough. For example, to configure the Dita Open Toolkit we used to build in PDF format, we needed a specialist familiar with XSLT transformations.
I don’t know which programmers you will 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 assembled by one program or several programs for different styles will be needed
• how many languages will the program support and whether it will be possible to change the output language with a simple setup
An example of how to determine the number of documentation assembly tools is shown in the figure.
Fig. 2. Options for setting up a program for assembling documentation
When calculating the time allotted for programming, keep in mind that often this process takes several months. During work, the documenter may need new tables, headers, and so on, and then the program will have to be finalized.
Single source technology implies that the source files of a document (created by technical writers) and finished documents (created by a program for assembling a document) are different files. And these files should also be stored separately. It’s optimal to use the same version storage system as your company’s code developers.
Fig. 3. The principle of storing files in a single source technology
The structure of storing source files should be based on the following principle:
• the method of storing files for all technical writers should be unified,
• the names of documents should be standardized,
• versions of issued documents should not overlap,
• certificates collected automatically with the program code should be stored in the same place as the code.
The storage structure of the resulting documents should include:
• separate storage of various versions;
• within the framework of the version:
- separate storage for different formats;
- Separate storage for different locations.
At the final stage of implementation, you will need to train colleagues to work with new technology.
First of all, technical writers will need to master a new editor for writing text.
You probably also need to examine the list of tags that will be processed by the program to build documentation. For example, at DoxVision we use DITA specification tags .
If a part of the text was copied before using the single source technology, now it can and will need to be learned to reuse. In addition, colleagues need to be familiarized with new data storage structures and carefully monitor that this standard is respected by all.
If the implementation is successful, the quality of the documentation being developed will increase significantly, and the cost of its production will decrease. Technical writers will enjoy their work more, 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 it will take the same amount of time to transfer previously developed documents to a new format.
For information: a lot of materials on DITA are collected on the DITA Writer website, and there is a list of references there .
I hope this material will be useful to you and will help you switch to a new technology quickly and painlessly!
Recently, to create all sorts of manuals for the operation of complex software systems, the use of a single source technology, which involves the reuse of any texts or images in the developed set of documents, has become increasingly popular. Not so long ago, we began to use this technology for the development of references and printed documents of DoksVision, and in this article I want to share my experience.
Why did we choose single source technology?
Those who are familiar with DoksVision company know that the main product we are developing is the Docsvision platform, and in addition to it, many additional applications and modules are released. Since 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 in full or with minor changes. This approach (given the regular release of new versions for all products) was very laborious for technical writers, as the vast amount of descriptions available did not allow us to track changes in all repeating sections and quickly make changes to many documents at once.
There were other difficulties:
• The editor in which the development was carried out did not imply several technical writers working with the document at the same time, which made it difficult to organize team work on the project.
• Customers contacted the company with requests for documents in different formats: some preferred information, others needed the ability to edit text or print. We did not have such an opportunity.
• We also wanted all issued documents to look in the same style. But due to the human factor, we could not achieve this in any way: the provided document template allowed us to make changes, and someone regularly changed it at our discretion, which spoiled the general impression of the company's documents.
At a time when the number of minuses overwhelmed our patience, it was decided to radically change the way documents are developed. As a result, we opted for 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 have already been taken into account. The decisive factors for us were the following:
• the ability to issue documents in different formats (PDF, HTML5 and XHTML, Eclipse Help, TocJS, HTML Help, Java Help, ODE, RTF, troff),
• hard structure of sections due to typed "topics" ( concept, task, reference, etc.)
• the ability to simultaneously work on a project for several employees.
We selected the technology and began to draw up a plan for its implementation.
Planning
At the beginning of the journey, we made a plan, which, of course, had to be adjusted. Here I give a set of stages in a strict sequence of execution, which (in our opinion) is optimal for solving the task. I draw your attention to the fact that the plan is suitable for the transition to any single source technology (not only the DITA that we have chosen).
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 recall those specialists who can assist with the implementation. Upon transition to the new system, we needed:
• Designer - helped prepare design layouts for documents
• Programmer - set up a tool for assembling a document in several formats.
A technical writer coordinated all these works.
Instruments
New technology implies the use of new software tools, so at the first stage of implementation, you will need to select and purchase some software. At a minimum, you will need:
• an editor for technical writers (we selected the Oxygen XML Author)
• a tool for assembling documents from the source format to the final one (we selected the DITA Open Toolkit to convert XML files to the supplied pdf and xhtml formats)
• storage system for source files and resulting 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 a professional version. I note that support for working with DITA is implemented in almost all the most popular editors for technical writers (Oxygen XML Editor, XML Mind, DocBook, AuthorIt).
The choice of a tool for assembling a document may not be necessary if the acquired editor allows you to assemble a document in the format and format required for release. By design in this case, I mean the standard adopted by your company: fonts, logos, color design, format of final documents, etc.
The storage system can be used the same one that the developers in your company use to store the program code - in this case, you can save on the purchase. You only need to come up with a good way to organize the repository, 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 in the structure of the documentation, and also so that it would be possible to formulate a task for the designer to style.
What will need to be standardized:
• 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 acceptable types (title page, introduction, chapters, sections, list of documents, applications)
• composition elements for each element of the structure (for example, for the title page: logo, product name, system name, version, document type)
• list of final formats (pdf, odt, xhtml, etc.)
• list of localizations (Russian, English, etc.)
• method of numbering product versions and versions of issued documents for the product I will
explain why such a strict standard is needed. As an example, consider the front page of the Docsvision documentation, which in the help and in the printed format, although it looks in the same style, differs in the composition of the elements and the way they are designed. For example, in the help there will be a description of the purpose of the document (which is in printed format not on the title page, but in the "Introduction" section), a search field and a table of contents. Please note that the rest of the text of these sheets is completely the same, is defined 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 then flow smoothly into the design layouts, and from there - into the program for assembling the final documents. If there are many mistakes, all work will have to be started anew.
Design
At the design stage, it is necessary to prepare graphic layouts of the documentation so that at the stage of setting up the tool for assembling the document, the programmer had a clear understanding of how the help web page or a printed sheet should look.
It is advisable to familiarize the designer in advance with the Style Guide used in the company, and if suddenly he is not (this happens often), then at least with the company's website.
Layouts need to be prepared:
• for each of the previously standardized formats of final documents, for example, a separate set of images for pdf and a separate set of images for xhtml-help
• for each of their standardized styles (for example, if different products are used in accordance with the company’s style color spectrum)
• 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 agreed with the company’s management and then you can proceed to the setup stage.
Customization
As I have already warned, you will probably need to connect programmers of various specializations to complete the setup. Building certificates requires knowledge of CSS, and the best way is to have a layout specialist. And to set up output in print formats, only typesetting may not be enough. For example, to configure the Dita Open Toolkit we used to build in PDF format, we needed a specialist familiar with XSLT transformations.
I don’t know which programmers you will 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 assembled by one program or several programs for different styles will be needed
• how many languages will the program support and whether it will be possible to change the output language with a simple setup
An example of how to determine the number of documentation assembly tools is shown in the figure.
Fig. 2. Options for setting up a program for assembling documentation
When calculating the time allotted for programming, keep in mind that often this process takes several months. During work, the documenter may need new tables, headers, and so on, and then the program will have to be finalized.
Storage
Single source technology implies that the source files of a document (created by technical writers) and finished documents (created by a program for assembling a document) are different files. And these files should also be stored separately. It’s optimal to use the same version storage system as your company’s code developers.
Fig. 3. The principle of storing files in a single source technology
The structure of storing source files should be based on the following principle:
• the method of storing files for all technical writers should be unified,
• the names of documents should be standardized,
• versions of issued documents should not overlap,
• certificates collected automatically with the program code should be stored in the same place as the code.
The storage structure of the resulting documents should include:
• separate storage of various versions;
• within the framework of the version:
- separate storage for different formats;
- Separate storage for different locations.
Training
At the final stage of implementation, you will need to train colleagues to work with new technology.
First of all, technical writers will need to master a new editor for writing text.
You probably also need to examine the list of tags that will be processed by the program to build documentation. For example, at DoxVision we use DITA specification tags .
If a part of the text was copied before using the single source technology, now it can and will need to be learned to reuse. In addition, colleagues need to be familiarized with new data storage structures and carefully monitor that this standard is respected by all.
What is the result
If the implementation is successful, the quality of the documentation being developed will increase significantly, and the cost of its production will decrease. Technical writers will enjoy their work more, 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 it will take the same amount of time to transfer previously developed documents to a new format.
For information: a lot of materials on DITA are collected on the DITA Writer website, and there is a list of references there .
I hope this material will be useful to you and will help you switch to a new technology quickly and painlessly!