A primer on primers

A primer (rhymes with dinner) is subset of information included in an encrypted message. The recipient of the message uses the primer to decode the message. In other words, the key to translating the message is contained within the message itself.

A spectacular example of a primer was presented in the film Contact. An extremely long and complex message written in a mysterious code is received from deep space. The scientists scramble to decode the message, but are unable to because they cannot correctly align the symbols at the edges of the thousands of pages contained in the message.

In this scene, three of the pages appear on a large monitor:

Someone discovers that the documents are actually three dimensional. By "folding over" the pages into each other to form a virtual cube, they magically line up, as shown here:

Not only that, within the edge of each page is the primer, the key to translating the message into Earthspeak, including the symbols for true and false:

Using the primer, the scientists are able to translate the message into a user guide that describes how to build an enormously complex machine.

* * *

All documentation contains primers to help the user understand the contents of the document.

Within traditional documentation, primers include:

• a section explaining the contents of the guide and its audience 
• a table of contents and index to guide the reader to the correct topic
• standard document conventions describing how various items are presented in the guide, including: UI elements, paths, code samples, optional items, notes, warnings, and so on
• instructions on how to view, search and annotate the document (if possible)

Through these items, the information required to understand the document is included in the document itself. It is the inclusion of this information within the larger document that enables this information to be a primer.

In additional to external primers (which are visible to the end user), you can also create internal (private) primers. These are elements which only you and the reviewers can see, and include:

• questions and comments for reviewers, tagged so that a reviewer can quickly navigate to them
• notes that apply only to the technical writer, for example, reminders of tasks the writer needs to complete

Again, the principle of the primer applies: information to help understand the message is included in the message itself.

These uses of a primer, effective as they are, are nowhere near as powerful as those in the next generation of documentation: XML. XML strips away all visual formatting in a document, replacing it with pure coded and tagged text. This allows you to easily add meta-information (in the form of additional tags) within the document itself.

An example of this is an XML Schema Guide, a highly technical document describing various programming objects, classes and variables that developers can use. It is possible to create a traditional document that describes these things. However, when the schema changes, for example, if an object is renamed or deleted, the writer must manually update the document.

To avoid this, writers and developers can work together to create a schema that is self-documenting. That is, within the schema itself are documentation tags. By updating the information within these tags, and then using an application to transform the schema into a document, the writer can create a schema guide that accurately documents the objects in the schema and displays the relationships between those objects through hyperlinks.

Another example is an installation guide for an application that can be installed under a wide variety of environments. Each portion of the guide that applies to a specific environmental scenario can be tagged accordingly, for example:

• operating system: [Linux], [Unix], [Windows], [Mac]
• database: [Oracle], [MS SQL]
• collaborative software: [Sharepoint], [Groupware]

Using an online application, the end user selects their specific environmental combination then submits a request for the guide. A custom-built guide is then automatically assembled. For the writer, this means no longer having to maintain multiple versions of the guide or use complex "if/then" statements throughout the document (e.g. if you are using Windows, then..., if you are using Oracle, then...)

The message for decoding the guide is literally embedded within the guide itself - the purest form of a primer.