Yes, there are naming conventions for custom DITA attributes to ensure consistency and clarity in documentation. These conventions help maintain a standardized approach to naming attributes, making it easier for content creators and developers to understand and use them effectively.

The key principles to DITA attribute naming conventions are using descriptive names, following a consistent prefix, using camel case or underscores, avoiding special characters and spaces, being concise, avoiding reserved keywords, and documenting custom attributes.

Use Descriptive Names

Custom attribute names should be descriptive and convey their purpose or use. A well-chosen name provides clarity about the attribute’s role in the content.

Example: Instead of using a generic name like “@custom1,” use “@productVersion” to indicate that the attribute represents the version of a product.

Follow a Consistent Prefix

Prefixes can indicate the type or category of the attribute. Common prefixes include:

• @prop: Used for generic properties.
• @meta: Used for metadata attributes.
• @data: Used for data-related attributes.
• @custom: Used for custom attributes.

Example: “@propAuthor,” “@metaDescription,” “@dataReleaseDate,” or “@customFeature.”

Use Camel Case or Underscores

Attribute names can be written in camel case or separated by underscores for readability.

Example (CamelCase): “@userRole,” “@customAttribute“

Example (Underscores): “@user_role,” “@custom_attribute“

Avoid Special Characters and Spaces

Attribute names should consist of alphanumeric characters and underscores only. Avoid using spaces, hyphens, or special characters.

Example (Incorrect): “@user-role,” “@custom attribute“

Be Concise

While descriptive names are essential, try to keep attribute names concise to avoid excessive verbosity.

Example (Concise): “@platform,” “@version“

Avoid Reserved Keywords

Avoid using DITA reserved keywords or attributes to prevent conflicts and confusion.

Example (Avoid): “@class,” “@outputclass“

Document Custom Attributes

Always provide documentation or comments explaining the purpose and usage of custom attributes to assist other content creators and developers.

Example (Documentation Comment):

<!-- @customAttribute: This attribute stores custom data for special formatting. -->