Crafting meaningful topic titles

Writing accurate, concise and consistent topic titles is an important challenge for DITA authors. Guidelines for crafting title text make this task a little easier.

In topic-based authoring, chunks of information have a greater need to be self-supporting, or standalone. This means that topics should be able to be read on their own, without reliance on what comes before or after. A topic with a heading of Introduction cannot be standalone, because it doesn't adequately describe what the topic is about. Introducing the Supara Liberty is a better label.

The greater importance of titles in semantic, structured authoring environments means that labelling (and other forms of cataloguing) needs to be thorough, and time and skill must be devoted to crafting meaningful titles.

In addition to helping the reader understand what a topic is about, titles should also help the reader identify what kind of topic it is. From the topic title, readers should know whether the topic will help them understand something, help them do something, or provide supporting information. This can be done by using different phrasing for titles for topics of different information types.

Titles must be meaningful, easy to read, accurate, concise and consistent.

When composing titles, try constructing them as sentence fragments. A useful technique is to re-write the title after the content of the topic and the short description are complete.

Some more specific guidelines are:

Do not use definite (eg, the) and indefinite (eg, an) articles (Engine, not The engine).
Use the singular, not plural (Engine, not Engines).
Do not start titles with generalised phrases (Security and Maintenance, not About security and Introduction to maintenance).
Do not use the ampersand character (Controls and switches, not Controls & switches).
Prefer the present participle (-ing form) verb and the imperative to the infinitive (Starting the engine or Start the engine, not To Start the Engine).
Do not attempt to use line breaks.
Use plain language.
Aim to use no more than eight words.
Use sentence case.
Use qualitative words to make the title more specific (reducing report length, not report length, or advantages of forced induction engines, not forced induction).
Ensure that the titles can be understood out of context.
Use consistent syntax and parallel construction.

To help the reader identify the information type by the title, use the following guidelines.

Information Type	Syntax	Examples
Concept	Start with a noun or adjective	Client window, Supara Liberty features, Important Considerations for Engine Modifications
Task	Start with a gerund or present participle, and use singular nouns	Resetting the odometer, Printing the audit report
Reference	Start with a noun or adjective, and include the reference construct (eg, table, list, etc)	Specification table, Product code list