About Documentation Framework
If we use an XML editor, Oxygen with DITA for example, we have to define the type of a document beforehand. And this tool is good at handling large documents, for example, a document with 200 pages in PDF format.
We must define one of the following types:
- Instruction, for example, Installation Guide, Deployment Guide, or Configuration Guide. All or most of all the topics in the guides are Tasks.
- Description to describe a new function, feature, or product. The topic types in such documents are Concepts or References.
- Mixture of the instruction and description. For a function, we can create a guide with descriptions in the first part, and instructions in the second part.
Of course, there’re other types, for example troubleshooting.
As for the SVG figures, we can use SVG figures for flow charts. We can use plantuml to draw the figures, save as SVG, and insert to the documents. But we use more eps graphics in Oxygen. Eps graphics are clear and take less space, and they can be used for future update. The eps graphics are drawn in Adobe Illustrator. We can also insert png in Oxygen, but it takes more space, and the system is slow when inserting a png figure into a topic.
Markdown files can also be edited in Oxygen and they can be converted to dita files. Oxygen web is a lightweight editor compared with the Oxygen application. But both Oxygen and Illustrator need to be paid. The XML editor has more tags, and is good at handling complicated and large tables, and converting documents to PDF format. They should be used for the products in the fields such as machinery, automobile, and chip. The disadvantages of xml editors are as follows:
- Money and efforts to purchase and maintain the tools. If Oxygen is bought, a revision management system is also needed.
- We have more strict or serious rules during the writing, and we can’t write in a flow in one document. We have to do one topic by one topic.
- Coordination with engineer contributors is not easy. They won’t access the working environment easily.
We can adopt some good manners from DITA:
- Try to separate the description and instruction in mindset
- Use less links as possible or use them in a smarter way
- Use less levels as possible
Items 2 and 3 are hard for HMTL documents since we have to use this way to direct the users. But an ideal way for the users is to find the target document and target section as quickly as possible.