Structure and Guidelines

Short descriptions in DITA follow specific structural and writing guidelines to support usability and content reuse.

Short descriptions appear in all DITA topic types. The <shortdesc> element must appear immediately after <title>, before the main body element.

Universal Structure Elements

  1. Purpose Statement: What the topic accomplishes.
  2. Context Clue: When or why someone would use this information.
  3. Scope Indicator: What's included or excluded (when helpful).

Topic-Type Specific Patterns

  • Concept Topics: Focus on what and why.
    • Pattern: "Brief definition + why it matters."
    • Example: "A microservices architecture divides applications into small, independent services that enable faster development and improved scalability."
  • Task Topics: Focus on goal and context.
    • Pattern: "Goal statement + when to perform."
    • Example: "Configure two-factor authentication to enhance account security when setting up new user accounts or updating security policies."
  • Reference Topics: Focus on scope and intended use.
    • Pattern: "Content scope + intended use."
    • Example: "Complete API reference for user management operations, including authentication, user creation, and permission assignment."
  • Glossary Entries: Focus on definition and context.
    • Pattern: "Clear definition + domain context."
    • Example: "Application Programming Interface (API) - a set of protocols that enables different software applications to communicate with each other."
  • Troubleshooting Topics: Focus on problem and solution approach.
    • Pattern: "Problem description + resolution method."
    • Example: "Resolve email delivery failures caused by connection timeout errors through network and configuration troubleshooting."

Length Guidelines

  • Optimal Length: 25-50 words (approximately 1-2 concise sentences).
  • Too Short (<15 words): Usually lacks sufficient context.
  • Too Long (>75 words): Defeats the purpose of quick scanning.
  • Mobile Consideration: Short descriptions often appear in mobile interfaces; test readability on small screens.

Writing Style Guidelines

  • Keep it to 1-2 concise sentences.
  • Don't repeat the title; instead, expand or clarify it.
  • Use active voice (e.g., "Configure settings" not "Settings can be configured").
  • Use present tense (e.g., "Explains how to..." not "Will explain how to...").
  • Use specific language (e.g., "Configure SSL certificates" not "Handle security stuff").
  • Be user-focused: Start with the user benefit rather than the system feature.
  • Avoid procedural steps or overly technical jargon that might confuse the audience.
  • Tailor to a human reader, not just for automation.

Sample XML Code


<concept id="cloudintro">
  <title>Introduction to Cloud Storage</title>
  <shortdesc>Cloud storage allows users to access and store files via the internet.</shortdesc>
  <conbody>
    <p>Cloud storage reduces dependency on local hardware...</p>
  </conbody>
</concept>