Online groups, winter 2010

DocBook

To produce most documentation, one organization uses unstructured FrameMaker. However, a small part of the documentation is written with DocBook. The organization does not have a technical communicator. The software developers update the documentation. The organization wants the software developers to be able to work on different parts of the documentation at the same time.

A freelance member has a short contract with the organization. She knows that FrameMaker 9 can deal with DocBook. However, she wants to find a cheap alternative editor for DocBook, so that the software developers can work on different parts of the documentation at the same time.

A member suggested that the best option is to use FrameMaker, because FrameMaker can use DocBook. If FrameMaker is set up to use DocBook, the content files can be saved as XML. Therefore, the content can be edited in all text editors. Many text editors are free. However, if you use a text editor, then you need some method to make sure that the XML conforms to DocBook. To work directly with styled DocBook content, you need support for the schema and for the style sheet.

The appearance of the output can be changed easily in FrameMaker. To change the structure in DocBook is difficult because DocBook is complex.

Members suggested the following resources:

Single-sourcing

A member wants to establish a new system for documentation. The documentation formats include websites, printed manuals, and PDF files. "How easy is it to integrate brochures, web content, help and user manuals by using 'common' text? Surely these items have different audiences." Therefore, how useful is single-sourcing?

Many tools are available, but some members think that one tool cannot fulfil all the requirements.

Single-sourcing decreases costs. With content management systems, a decrease in cost of 30% is possible. In one project, the Author-it CMS paid for itself in approximately six months. Additionally, large decreases in the cost of translation are possible.

Although marketing documents, websites, and user documents are for different users, content such as product descriptions can be shared.

The benefit of single-sourcing is dependent on how much of the content is reused. Decide what content will be modularized (sections, chapters, warnings, images). Not all the content needs to be modularized. Sometimes, you can use complete documents as modules.

Translation or localization?

In reply to a question about translation and localization, a member gave his experience of the localization of documentation for telecommunications hardware and software. Localization was necessary because of the following reasons:

|

RSS feed