Metadata

From TechWriter Wiki

Introduction

Metadata is 'information about the information'. Here, it is used to refer to 'information about a document'. This can be thought of as the traditional front matter, or back matter, and is, broadly, the information about a publication that you need to record within the publication itself - that is, not information that may be contained in a Document Management System.

Things to consider

Document identifier

Every document must have a unique, unchanging identifier. The title is not enough - titles can change. How unique the identifier is depends on the scope of the publication - or more specifically, the degree to which it will be seen alongside other publications. For example, if publications for one product will be housed in the same library (or other repository) as publications for another product, then it may make sense to code the product identifier into the document identifier. On the other hand, if publications are always housed separately per product, then there is no strong driver for including the product identifier in the document identifier, and the same publication for separate products could have the same document identifier.

There are a number of options for document identifiers. Some of the more common ones are discussed below:

Hierarchical

With hierarchical document identifiers, the identifier also indicates the grouping within which the document exists. This grouping may be by product, or functional area, or some other classification.

Sequential

Strictly speaking, a document identifier is just a simple form of reference that identifies a unique document. If there is no strong case for building 'logic' into the document identifier, then it may be sufficient to just use a simple sequential document number - perhaps starting at "1" (or more likely including leading zeroes, so "001") and working sequentially up.

In reality, it is likely that some degree of logic or grouping will be built into the identifier - perhaps to identify the product or the type of document. In the latter case you could use "PR-001" and so on for process documents, and "UI-001" and so on for user instructions. Even if no logic has been dictated, it may be worth thinking about possible uses for one and building this in from the outset - it is much more work to 'retro-fit' a nomenclature to document identifiers once the documents have already been written and published.

Arbitrary

As described above, there does not have to be any great logic behind the document identifier. However, there are still some basic guidelines that it makes sense to follow:

• Do not include the author's name or initials. Authors come and go, and documents may be worked on by multiple authors. In the long run there is no good reason for identifying the author (but see comments under Author below.
• If an arbitrary text string is used then this should in some way relate to the title or function of the publication. For example, for a user procedure with a title of "Recording a customer payment" you could use "RECPYMT". However, when doing this be wary of variable length (and in particular lengthy) identifiers, or documents with very similar titles. Where multiple authors will be working on a set of documents it may be wise to provide guidance on how identifiers should be formed.

Version number

A version number (or revision number) is necessary so that readers can ensure that they are referring to the latest version of a document. However, note that the version number is only really useful when comparing one copy of a document against another. If the user is only in possession of a single version of a document then they still don't know whether this is the latest version or not. The use of a Publication date can help here - especially when this is used in combination with the Date of last review and Date of next review.

Publication date

The publication date is useful to allow users to identify the 'currency' of the document. One could argue that if the publication date is provided then there is no need to provide a version number. However, people tend to remember (small) numbers much more easily than dates. It is therefore a good idea to provide both.

Owner

The person or organization that must be consulted regarding changes to the publication. This is the person who should be called upon to arbitrate in discussions regarding the publication (for example, disagreements over its validity).

In some cases, it may be sufficient to provide the name of the person or organization to whom all inquiries concerning the publication should be directed.

Review dates

Some documentation systems require that publications are (re)reviewed periodically - for example, once a year - to ensure that they are still current. Under such systems, it is necessary to record the date on which the document was last reviewed, and the date on which it should next be reviewed (or at the very least, the date on which it should next be reviewed, working on the assumption that the date on which it was last reviewed is the publication date). The purpose of this is to confirm to the user that the document they are reading is still valid (or not). This is more likely to be relevant for publications such as policies and processes. Where the publication relates to a product or software application it can largely be assumed that the publication is current and valid unless the product or application itself changes - assuming that the document specifies the supported product level.

Author

For most work provided by the Technical Author, it should not normally be necessary to identify the actual author of the document. Identifying the owner should be sufficient. Typically, authors will move on to other work (or the authoring team will be disbanded at the end of the project) and so the named author may no longer be available. However, there are a few circumstances under which it may be worthwhile including the author's name in the metadata.

• Where the author is a known authority on the subject, identifying the author can add a level of authority to the document.
• Identifying the author can lead to a greater sense of 'ownership' on the part of the author, and may encourage them to produce better quality work. This works in both a positive way (the author will gain kudos for a job well done) and a negative way (the author will not want their name to be on a sub-standard document).

Reviewers

Version history

a.k.a. change log