|
|
|
 |
 |
 |
 |
|
One from All and All from One |
|
by Stephen Helms |
How many of the following documents does your company keep creating from scratch?
• Reference books
• Tutorials, training and presentation materials or on-screen documents
• On-screen help
• Web pages for the internet or intranets
• CDs for off-line browsing. Wouldn’t it be easier to create just one document that was used a single source for all the others? It sounds like a great concept but is it really possible or another idea that is just too good to be true? Stephen Helms is one man who has knows how it’s done and just how effective it can be. Here he describes how he solved one company’s documentation demands using the magic of single-sourcing. |
|
|
Often, business managers and software suppliers provide viewable and printable documentation in the form of Adobe Acrobat Portable Document Format (PDF) files on CDs. They are also (obliged, almost) to provide help on-line, either as HTML Help or internet help. The material is often printed as a hard copy user guide as well. The content of all these forms of documentation may be identical – so why continue to re-invent the wheel? This single-sourcing has been the Holy Grail for many a documentation specialist too and has often proved an elusive goal. CHL is proud of the fact that it has now achieved the goal on a number of projects for clients in France and the Far East. Admittedly, to achieve it requires a formal discipline and an ability to create and maintain standards, as well as understanding the tools of the trade, but it is an eminently demonstrable, teachable and transferable skill set. Atos Origine Through a French associate, CHL was called in to provide advice on producing the online help and a Printable User guide for the technical administrators of an Internet-based Banking and Portfolio Management system called Worldline Broker. The client, a large software house called Atos Origine, expressed a preference for having the source in Microsoft Word, since this was their chosen, in-house word processing package. Following a detailed study concerning the structure and content, some experiments were undertaken with a number of the possible tools which could be used to create consistent quality, printable documents as well as help available on demand via the Internet. Using Word (2000) as the source and Adobe Acrobat for the printable form (Portable Document Format of PDF), three other tools were also tested for their abilities convert the source into standard HTML pages and retain and display the hierarchical structure. The tools tested were the then current versions of eHelps RoboHelp, ForeFronts ForeHelp and Virtual Medias Hypertext Development Kit (HDK). RoboHelp and HDK could both import standard Word documents while ForeHelp accepted Rich Text Format (RTF). It is simple enough to save a Word document as an RTF file but it is an extra step and unfortunately, the hierarchical structure created in the Word document using standard paragraph styling was not respected. Similarly, RoboHelp imported the document contents as a set of topics, but the hierarchy was not respected and this had to be re-imposed by hand. The HDK Import document feature not only was able to import a document and convert it into an exact equivalent structure, but was also able to cope with a fairly complex Master and Sub-Document set of Word Documents. This became the chosen route. The source comprised one Master document and 12 sub-documents which referenced 260 screen captures or images from the system all in one folder on the hard disk, taking up 7.86 Mb. The Word documents stayed relatively small – 1.89Mb – since all the images were linked but not saved in the documents and this almost certainly contributed to the stability of the route towards the Holy Grail. Indexing and cross-referencing to bookmarks was also respected and these were converted in to index items and hyperlinks within the HDK project. The outputs available included:
• HTML Help
• Standard HTML
• Standard HTML with a Java Table of Contents and index system The latter was recommended and accepted by the client since the navigation was made simple using an interface similar to Windows Explorer. The resulting system comprised 572 files (gifs, jpgs and HTML files) totalling 6.14Mb. Using the standard Adobe Acrobat PDF output from the Word Master document worked slowly, but without problem, to produce an 8.3Mb PDF file. While the structure and the hyperlinks were respected, these latter were not visible unless the mouse hovered over the hotspot. With a document of 131 pages this was not acceptable so all the cross-references in Word were coloured blue and the hyperlinks were then easily visible when converted to PDF. Certainly, the project demanded a suitable Word template to be created and the discipline and attention to detail to ensure its success. Clearly it was worth it – the client subsequently ordered three other documents, including the systems Installation Guide, to be created in the same way.On the Ball The same basic technique was used for the host broadcasting organisation of the 2002 FIFA World Cup™ both in France and South Korea. The web site had been designed and developed by Stephen Helms of CHL and it was essential to have back up resources to be able to continue to maintain the site on the occasions he was absent. So the procedures for doing so were written in Word and converted to Adobe Acrobat PDF files and an HTML Help file to suit the reading preferences of the individuals concerned. Despite the availability of some very clever documentation technology, many businesses are still producing all their documents from a variety of sources when they could use only one. The benefits to authors and companies are enormous in terms of time and money saved, standardisation of formatting, and maintenance. One day we will wonder why we did it any other way.All articles on the Quality Authors web site are copyright and are the property of the authors, who have asserted their moral rights. For permission to use an article, please contact the author directly.
|
Article Index
|
|
|
|
 |
|
