knowledgeDoc

Preparing online content for Word and PDF outputs

Neil Woolley
by Neil Woolley

In a previous article, I discussed reformatting and preparing Microsoft Word documents to import into our authoring tool; enabling us to create a variety of outputs, including online help.

A bit like a hobbit’s tale ‘There and back again’, our customers often want Word/PDF versions as well as the online content. So once we’ve gone to the trouble to bring in Word documents into our authoring tool, we need to be able to:

  • publish the reformatted and updated documents back to Word
  • save from Word to PDF.

During my 2013 trip to Scotland, I had the pleasure of going to Robert Smail's Printing Works. The printing presses use manual typesetting and used to be powered by a water wheel. After the page was printed the required number of times, the apprentices had to dismantle the ‘forme’; they were told to ‘mind their ps and qs’ so they put the ‘cast metal sorts’ into their correct slots in the type case (a compartmentalised wooden box). We’ve come a long way since those days.

It’s rare to provide printed user guides anymore. In fact, it is becoming difficult to justify the cost of printing some manuals. One of our customer’s set of manuals is over 9,000 A4 pages (that’s nine reams of double-sided paper!).

Adobe’s PDF has become a standard way for printable documents to be provided to end users electronically. PDFs can be viewed, searched and printed.

Before we can create a PDF, we first need to output to a Word document. The format of the Word document determines the PDF’s title page, headers and footers, styles and so on.

Some of the steps we use to output from our authoring tool back to a Word document are:

  1. Apply and test the organisation’s Word template with representative content:
  2. Our work earlier to set up the organisation’s Word template pays dividends at this stage.
  3. Publishing content back to Word can be very quick once all the objects are set up and tested.
  4. Usually the content is almost identical between the online (web, context-sensitive) and printable versions (Word, PDF).
  5. Apply templates to topics; this sets page numbering, headers and footers, section headings and whether topics need to throw a page break.
  6. Scale the graphics to fit on the printed page. We can apply a graphic template to ensure the graphic looks great online, and is as big and clear as it can be on the printed page.
  7. Recapture poor screens. If we have access to demonstration systems or web applications, we prefer to recapture fuzzy screens; we capture the part of the screen needed and do it well.
  8. Add pagination to steps. For example, if you have a step describing what to do, you want to keep the accompanying graphic on the same page as it. Word has a good feature ‘keep with next’ that is not supported in our authoring tool. We have a handy technique to force page breaks using a special object.
  9. Add ‘last modified’ at the end of topics. We always include a ‘last modified’ date and time for each topic output to the online help; users can see if the topic was recently updated. Our ‘last modified’ object also resolves any end-of-topic formatting issues.
  10. Add topics that add ‘Intentionally left blank’ onto blank pages. Surprisingly, the number one reason users contact the support staff about the documentation is that there might be a blank page just before a new section; they are concerned that they are missing a page of information. We avoid this phone call by inserting a topic that includes a page break and the phrase ‘This page intentionally left blank’.
  11. Use an ‘after publish’ macro. We have a Word macro that trolls through the output from the authoring tool and resolves many common formatting issues, such as table formatting.
  12. Check the Word document after it is published. We check for issues, resolve them in the authoring tool and republish to Word. Eventually there are usually one to two things left that can only be resolved by editing the final Word document.

Once we have a final Word document, we can output it to a PDF. From Microsoft Word 2010 onwards, you can select File > Save As and select PDF from the Save as type drop-down list. This allows anyone to easily create PDFs without needing other tools.

One of our customers uses the latest Word document to mark changes to be applied during the next quarterly review.

PDFs are loaded by our customers onto their intranets (internal use) and extranets (external use). We also have a link to the PDFs from the home page of the online help; users mostly use the online help but can open the PDF to view and print pages.

Back to blog home.