DITA maps and topics benefit from naming conventions that provide a consistent and organized structure for content. These conventions typically involve using meaningful and descriptive names, adhering to a naming pattern, and avoiding special characters or spaces to ensure clarity and consistency in DITA documentation.

Naming Conventions for DITA Maps and Topics

Naming conventions for DITA maps and topics help maintain consistency and clarity in content organization. These conventions often include descriptive names, naming patterns, avoiding special characters, and using hyphens or underscores.

Descriptive Names

Use names that accurately reflect the content of the map or topic. A descriptive name makes it easier for authors and users to understand the purpose of the map or topic.

Naming Patterns

Employ consistent naming patterns to structure the content. For example, an author might prefix all user guide topics with “user-” and all reference topics with “ref-” to instantly distinguish between them.

Avoiding Special Characters

Avoid special characters, spaces, and diacritics in names to ensure compatibility with DITA processing tools and to prevent potential issues during content generation.

Use of Hyphens or Underscores

When necessary, use hyphens or underscores to separate words within a name, making it more readable. For example, “user-guide” or “user_guide” instead of “userguide.”

Example

An organization uses the following naming convention for a DITA map and topics in a software documentation project.

DITA Map Name

software-documentation.ditamap
    

DITA Topic Names

user-interface.dita (Descriptive name for a topic about the software's user interface)
installation-guide.dita (A descriptive name for a guide about software installation)
api-reference.dita (A descriptive name for a reference topic about the software's API)
    

By following this naming convention, authors and users can easily understand the content’s purpose, and the structured naming pattern ensures that topics are organized consistently throughout the documentation project.