FLOWiki

(y)our wiki about all things technical communication

User Tools

Site Tools


dita:guidelines_for_writing_topic_titles

Guidelines for writing topic titles

Once you have decided which information you will include in a particular topic, you can choose an appropriate title for that topic. Well-chosen titles are crucial to the scannability of your document: they help users to quickly find the info they are looking for.

Reflect the content

A good topic title reflects the content of the topic. Because most topics answer a specific question, you can use (a derivative of) that question as your title. For example:

Information type Question Title
Task topic How do I insert batteries in my camera? How to insert batteries in your camera
Concept topic What is white balance? What is white balance
Reference topic What do these battery icons mean? Overview of battery icons

If you have a hard time finding a title that covers the content of a topic, that topic probably addresses more than one subject or includes several information types. You then have to split the topic into two or more smaller topics, so you can label them appropriately.

Be concise and specific

Concise topic titles are the best way to quickly guide the reader to the correct information. When you have written a title, always ask yourself if you cannot remove any words.

Although it might seem fun, avoid using puns, tropes and figures of speech: technical documentation is not the place to give your literary aspirations free course.

However, you should also take care not to become too concise: your topic titles should still be specific. Vague topic titles are meaningless and do not speak to the user. When you have written a title, you should ask yourself if you do not have to add a word or two. Instead of using “Introduction” or “Overview” as a topic title, for example, specify what you are introducing or which information there is in the overview (“Introducing DITA”/“Getting started with DITA”, “Overview of DITA information types”).

Use consistent syntax

Use the same syntax for titles of similar topics or - if possible - for all topics of the same information type. Like that, the user immediately knows which kind of information he will find in the topic and can decide whether or not he has to read it.

“How to insert batteries in your camera”, “Inserting batteries in your camera”, “To insert batteries in your camera” or “Insert batteries in your camera”, for example, are all valid titles for a task topic. If you choose one formulation and use it for all your task topics, users can immediately distinguish task topics from concept and reference topics.

dita/guidelines_for_writing_topic_titles.txt · Last modified: 2017/03/30 13:16 (external edit)