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:
- https://docbook.org
- http://wiki.docbook.org/topic/
- http://wiki.docbook.org/topic/DocBookAuthoringTools (for a list of validating editors and software that you can use to edit styled content)
- https://tldp.org/HOWTO/DocBook-Demystification-HOWTO/
- www.ptc.com/product/arbortext/editor/
- www.scriptorium.com
- Steve Rickaby's articles about structured FrameMaker, Communicator spring 2007 to spring 2008.
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:
- Safety regulations, restrictions on hazardous substances (RoHS), and legal requirements are different.
- Connectors are different. Wires have different colours.
- The format of telephone numbers is different.
- Telephone call services have different numbers. For example, 1471 is used in the UK, but the number is different in other countries.
- Some services are not available in all countries. For example, the US uses visual indication for voicemail, but this service is not available in some other countries.
- Default values are different in different countries.
- Different technologies are applicable in different countries. For example, different versions of ISDN are used in different countries.
- Some websites were translated. Therefore, different screenshots were necessary.
- To explain copyright and performance rights for music on hold, the documentation told people to look at an applicable website for their country.
RSS feed