Content Page Appearance - The Standard Document Type

Developing your Content - Life after Word

As you'll know by now, you can use The Manuals Machine for any type of content file that can be viewed under Internet Explorer. Whatever type of documents you have, they can be incorporated and indexed into a Volume.

XML content of any document type can be used, provided that stylesheets are available to convert them for display. If you obtain XML documents from external sources the stylesheets to display them in a clear readable form may already be available, or you could develop templates for your specific requirements. If your business receives materials like product details or purchase orders as XML documents, you would be able to store, organise and read these using The Manuals Machine. The 'Alternate Views' feature even lets you specify a choice of stylesheets for any document, so you could see your own inhouse view and your suppliers' or customers' views.

But what if you want to develop and maintain new pages, to write some documentation or manuals? What document type should you use? How to display it?

If you're the typical medium-size business to which our documentation services are targetted, and you need to write these types of materials, you'd probably think first of using Microsoft Word.

We developed The Manuals Machine's Standard Document Type and the Author/Editor to enable composition of XML-based content which has the look-and-feel of documentation developed using Microsoft Word. You can use them without installing any software, with a much smaller training requirement, and you can achieve high-quality outcomes with excellent productivity.

The Key Wordprocessing Constructions

Word and all other mature wordprocessing products offer a huge range of features. But to write business documentation, typically all you want to do 99% of the time is to prepare pages using a few common constructions: paragraphs, headings, almost certainly some bullet lists, perhaps some simple tables. You'll often want to include plenty of illustrations, and you require consistent appearance across all the content, even when it's developed collaboratively by several writers who may have personalised PCs. And you want to organise their output into books, manuals and user guides. And that's it.

The Standard Document Type

The Standard Document Type and the Author/Editor provide a simple and effective and high-performance solution to this requirement. They enable you very easily to prepare XML pages formed from the types of wordprocessing construction mentioned above.

They also enable you to set out the rules for organising and linking the pages in the Volume, including how they will be listed in the TOC and Alpha Index. And they enable you to integrate and organise other types of content such as PDFs.

The XML document type provides a set of rules for packaging your content as a sequence of components, which are the basic wordprocessing constructions listed above.  And if you do need something else, it's extensible. There are various ways in which you can add your own unique page components with their unique constructions and appearance.

For example if you are writing a book that employs particular house styles throughout - like the excellent series of reference books published by by Wrox Press, O'Reilly, IDG Press and others, you can accomplish this. Styled sections like coding examples, reference tables, hints and warnings (complete with little bomb or other icons) are all possible.

The Manuals Machine lets you define your own section styles and widgets, customise the appearance, and enforce stylistic consistency across all pages in a Volume. The methods for this employ standard practices for web pages and for working with XML - these are Cascading Style Sheets (CSS) and XSLT Templates. More information is provided under Customising Appearance using CSS and Extending Content Types.
House Styles could be used throughout a book
(acknowledgement: IDG Press)

You can also supply sections of display-ready HTML, which can be shown inline in your sequence of paragraphs, bullet lists and other wordprocessing elements.
Organising the Page - The Manuals Machine Page Model

The Standard Document Type employs a very simple model for page construction. The simplicity is quite deliberate: we considered using established document types such as DocBook and WordML, but considered that they were too complicated for the business users to whom The Manuals Machine is targetted. We wanted a "getting started" time of no more than an hour!

The appearance of a Manuals Machine Page is:

  • an optional header shown at the top of the page
  • one or more blocks

Each block comprises:

  • one or more elements

The elements are the standard element types provided by The Manuals  Machine:

  • paragraphs
  • headings
  • bullet lists
  • tables
  • listing examples
  • XML markup examples
  • images, and groups of 2 or 3 images
  • HTML
  • sound clips and video clips

Plus:

  • your own extension element types, if any

This toolkit is more than enough to build attractive, well-structured and illustrated reference documentation (this example is one of the Author/Editor Help Screens).
helpscreenexample.jpg
This page has a heading and two blocks each with its own title

Documentation authors do need to know and understand the page model of blocks containing elements, because it is exposed when they work on the page using the Author/Editor.

Numbering

Numbering can be supplied for both Blocks and Elements. Support for numbering is simple and extends only to block numbering and simple element numbering. If you require more you can supply your own custom XSLT stylesheet templates and use xsl:number (custom templates are the standard method for extending The Manuals Machine's content types).

In general we discourage elaborate numbering (it's for traditional printed materials not modern hyperlinked online stuff - how many websites do you see with section numbering? Does Windows Help have it?); we suggest you restrict any numbering to Blocks only. The main application that we see is for support and technical discussions over the phone, where numbering enables both parties to quickly lock on to the same section of content.

Incorporating Illustrations

Several methods are available for incorporating illustrations such as screenshots or photographs into a documentation page, and the Author/Editor provides quick and convenient tools for setting them up.

Simple images can be shown one, two or three abreast and have individual captions. You can associate images with Blocks to provide a newspaper-style effect, with an image to the right of a column of elements such as paragraphs and bullet lists - rather like the two illustrations on this page. You can also associate an image with an individual paragraph element, where it will be shown to the right of the text.

You can also include a series of images inside a table, to prepare tidy galleries. And there's a special subcomponent that you can put into table cells. This provides clickable thumbnails, that can be used to build attractive content navigation menus and launch sound clips.

Finally there's always the option to create any graphics effects that you wish, by providing sections of display-ready HTML, which can even include script code.

Could You Use Word Documents Directly ?

Perhaps you've wondered, if the objective is to prepare pages that look like Microsoft Word documents, why not just use Word documents. After all they can be opened inside Internet Explorer, so can they be used in The Manuals Machine?

The answer is technically yes, but please don't do it. There are several reasons, notably that performance and reliability are compromised. The reliability issue is not just operation of the software, but also to reliably control the appearance that can be achieved (because it can depend on factors that you can't control, such as differences between Word settings and styles between the PCs on which documents were developed and those on which it they are displayed).

Our advice is simply this: if you have legacy Word documents that you wish to display in The Manuals Machine, convert them to PDF. If you have to prepare major revisions, consider converting to XML and using The Manuals Machine Author/Editor.

Please also note our Support Statement under Distribution and Licensing.