|
If you offer documentation in various formats, you should consider single sourcing. From one project it is possible to generate:
 |
|
|
| |
 |
Online help. |
| |
|
User guides. |
| |
|
HTML files to provide product support from your Web site. |
| |
|
Installation instructions and administration manuals. |
| |
|
Quick reference material and management overviews. |
Are the cost savings significant?
In short, yes. There are two reasons why:
Is the quality of the online help and hard copy documentation the same as if I chose just one format?
Not quite, but it's close.
In terms of the features and aesthetics, the standard is equally as good.
The area of compromise is the writing style. Our technical authors and technical writers would normally adopt slightly different writing styles when authoring online help and hard copy documentation. When single sourcing, we adopt a 'generic' writing style.
Can't I just buy a software application that will do this for me?
Unfortunately, no.
Despite the claims made by some help development tools, it is not possible to just 'click a button' to generate both professional standard online help and hard copy documentation.
What options are available for creating single source projects?
Various different options are available. The most popular are:
|
|
|
| |
|
Use RoboHelp X5 As its name would suggest, RoboHelp's roots are in online help development, yet it is also capable of generating printed documents of a reasonable standard when used 'out of the box'. Armada has taken RoboHelp's single source capabilities to a higher level by developing a series of templates, macros and techniques that enable us to produce both first class online help and professional-standard printed documents from a RoboHelp project.
A RoboHelp single source project is perfect if you require documentation in various formats for a software application, and don't have a requirement to re-use this same information over and over again, e.g. for other similar applications. |
| |
|
Use Madcap Flare Madcap Flare is a versatile help authoring tool developed by the team who previously made up the core members of eHelp® Corporation, creators of RoboHelp.
With Flare, the underlying structure of your project is XML. Like RoboHelp, Flare is capable of generating both online help and printed documents of a high standard.
A Flare single source project should be considered if you require documentation in various formats for a software application, and you think you may want to re-use the authored text. |
| |
|
Develop a project using XML / DITA XML / DITA is ideal for medium and large organisations that produce vast quantities of documentation, particularly if there is a requirement to re-use the same content in different publications and the documentation is to be translated/localised.
Developed by IBM, the Darwin Information Typing Architecture
(DITA) is a topic-based XML standard designed specifically for technical publications. With DITA, content is authored in discrete units, making it easy to re-use it in different contexts. Because XML is format-neutral, the content can be published to differing media such as HTML Help (.chm), uncompiled HTML (e.g. for product support on the web) and print (PDF).
For further information about DITA, see:
|
| |
|
Use WebWorks ePublisher
WebWorks ePublisher is perfect if you already have content in Microsoft Word, Adobe FrameMaker or XML format and want to publish it in further formats such as HTML Help. Armada are experts in setting up files for use with ePublisher, and developing ePublisher templates (known as stationery), so that the resulting output in the different formats you require are of a professional standard. |
What has to be done?
The procedure our technical authors and technical writers follow when working on a single source project varies depending on which approach is being followed and what the requirements are. It typically involves:
|
|
|
| |
|
Deciding an appropriate writing style and method of organisation. The style of writing must be appropriate for the different formats you require. The content you generate must be divided into 'modules' (introductory sections, procedures, processes, etc.) that will 'work' in all formats. |
| |
|
Creating templates. Templates need to be created for each of the different formats you require, e.g. cascading stylesheets for HTML, Word templates for hard copy. When the documentation is output, most of the layout work is then done for you. |
| |
|
Making use of conditional build tags and expressions. As our technical authors and technical writers write your source text, they indicate which output formats each 'chunk' of information is to be included in, for example it is probably appropriate to include installation instructions in a user guide, but not in online help. |
| |
|
Creating macros. Even if you create templates, the documentation layout will still not be perfect when it is first generated. Some manual tasks have to be carried out. Most of these can be automated using macros. |
|
|
|
