Topic titles and topic file names

The best ways to name topics

The way that we name topics can have a significant effect on usability. Wherever possible, adopt a topic-based authoring approach and apply these topic naming guidelines.

Table 1. Topic naming guidelines
Topic type Syntax and examples

Concept

Begin the title with a noun or adjective, and use the singular unless plural really does make more sense. Don’t begin with an -ing word.

  • Overview of the network environment; Methodology for device management; About the interface

Task

Use the imperative voice, begin with a clear verb, and use singular nouns.

  • Launch the application; Delete the data table

Try not to begin with a gerund or present participle if possible — there is usually a better imperative form.[1]

  • Print the audit report is much better than Printing the audit report

1. Also note that the imperative form gives better search results — see Are Gerunds in Topic Titles Problematic in Search Results?

Reference

Start with a noun or adjective, and include the appropriate reference construct, such as 'table' or 'list'.

  • Specifications tables; Product code list; Workflow diagram

Related information

Topic file names

Some authoring tools take care of the file-naming (and URLs) for you (generally complex database-backed tools). Where this is not the case, adopt the following approach.

Keep the file names as close to the topic title as possible, within the limitations of the file system and web system.

Whenever you revise the topic title, be sure to also:

  • update the file name to match

  • update and redirect URLs, if appropriate

  • check for dependent cross-references and update as necessary

  • check for broken links in the output

To keep this simple and predictable, be consistent and use a file naming scheme. Use whichever file naming scheme is already in use for a project, or defer to kebab-case for web-based projects.

File naming schemes
kebab-case

Prefer this option for web-based projects, unless another scheme is already in use.

  • Remove all punctuation.

  • Use lower case only and replace all spaces with a hyphen.

PascalCase

Use this as an alternative if kebab-case is not ideal for some reason.

  • Remove all punctuation and spaces.

  • Capitalise the first letter of every word and retain upper case for initialisms.