The Concept Topic
A includes all of the information necessary to understand a set of ideas or constructs. It answers "What is xyz?".
Concept topics supports tasks and goals, not the other way around. 1 Use concept topics to:
- Naming standard: c_product_name.dita.
- Describe a system, product, or solution.
- Outline a process.
- Introduce tools and technology.
- Explain features, components, characteristics, restrictions, or capabilities.
- Define terms in more detail than you would a glossary.
- Describe benefits or help users to make choices between options.Note: The DITA Concept Topic description is documented in docs.oasis-open.org.
Title Guidelines
- Use nouns or noun phrases
- Use title case
Examples: "Media and Communication" or "Account Segments"
Style Guidelines
- Write an effective short description for your topic. Introduce the topic in the short description. You may want to:
- Define the solution, feature, or technology.
- Describe the benefits or importance of the concept.
- Briefly outline a process. Example: "Integrating your ChMS with Go Method consists of three steps that will take you about 20 minutes."
- Do not start your short description with "You can..." or "Admins can..."
- Consider information the user may not know. For example,a church secretary may not understand some of the reasons emails are delivered, which is key to fixing those issues when trying to communicate with members.
- Organize the concept and break up dense material with lists, images, summary tables, video, and so on.
- Add images or examples to describe the concept. A picture is worth a thousand words.
- Do not include tasks or other procedural or reference information.
- Avoid the use of sections where possible. The hierarchy of information should be defined in the ditamap via chunking and not through section elements.
Structure
Concept topics can contain the following elements.
- <title>
- Topic or section title. *Use noun-based title for concept topics. Ex. Profile Fields, User Roles, or Sacraments
- <shortdesc>
- Introduces the concept and show up in search results as the preview content. *Required.
- Define a broad term or idea.
- Describe benefits.
- Outline a process.
- <prolog>
- The prolog contains topic metadata, such as keywords, critical dates, the author (automatically inserted), and resource id's, which are used to link content to a software interface, contextually. You can add more than one resource ID to a prolog, but never use the same resource ID on more than one topic. The application name can be completed so that future information managers can understand which system utilizes the resource id. Example: Resoure ID - AdvancedUsers.lesson name and Application Name is "LMS".
- <conbody>
- Contains the description of the concept. This is where you add sections, paragraphs, and other elements, below.
- <p>
- The paragraph element is used to contain a collection of sentences that describe a single idea.
- <section>
- Contains a subsection that you can use to organize the conceptual information. We generally use these in release notes. Before using sections, consider if there is more value in breaking out information and then chunking back together. Ask could the information in the sub-section be reused elsewhere, or delivered to a separate channel, independently of the rest of the page. If so, the content probably benefits from breaking out to separate articles and then chunking together.
- <ol>
- Displays a numbered list.
- <ul>
- Displays content as unordered, bulleted list.
- <example>
- Ideas or drawings that supports a topic with relevant representations, models, or patterns.
- <dl>
- Displays a list of terms or short concepts and their definitions. While this is allowed, we generally place field descriptions in Reference topics and append or chunk, but it is important for the writer to know this is available.
- <fig>, <title>
- Provides a figure and caption so that you can insert graphics.
- <image> & <alt-text>, <object>
- Used to insert media, such as image, video, or interactive pdf. Complete the alt text so that screen-readers read back to visually handicapped users a description of the image. (Need help with alt text? Read why it's important and see examples in this article.)
- <note>
- A note element calls attention to or highlights a simple caution, warning, tip, or additional information. Use sparingly and set the Type attribute to "Tip", "Info", "Caution", or Warning". See when to use each type in Notes.CAUTION: No other Type attribute is formatted in our CSS.
- <term>
- Highlights new terms. (Use glossary template.)
1 Source: DITA Best Practices by Laura Bellamy