Topic, Content, and Media Types
Within R&D, we author or maintain the following topic types, primarily for external audiences, but occasionally for internal audiences as well. Detailed information about topic types, DITA elements, and attributes can be found at docs.oasis-open.org. In particular, it is helpful to understand the basic structure of all DITA topic types.
Organization of Product Documentation
Product content is generally organized as follows on a section by section basis:
-
Concept topic that provides an overview of a set of features along with benefits. For example, a concept topic for Go Method's Trip Planning might describe an overview explaining its use for various trips, events, camps, or retreats whether local or abroad. Examples, graphics, videos, or other media may be used to help the reader better understand the benefits or applications of a set of features, tool, or app.
-
In some situations, concept topics may be followed by reference topics that provides a list of definitions, tables, or charts that are essential for progressing through the section.
-
Task Topics for each task-based procedure follows the concept topic.
-
Reference topics frequently follow the tasks topics.
-
Relationship tables should not be lengthy but well thought out, providing references to information not easily seen in the table of contents.
ACST Topic Types
- ACS Concept Topic
- Based on the standard DITA Concept Type. "Concepts provide background that helps readers understand essential information about a product, a task, a process, or any other conceptual or descriptive information. A concept might be an extended definition of a major abstraction such as a process or function. Conceptual information might explain the nature and components of a product and describe how it fits into a category of products. Conceptual information helps readers to map their knowledge and understanding to the tasks they need to perform and to provide other essential information about a product, process, or system."
- ACS Task Topic
- Based on the standard DITA Task Type. "Tasks are the essential building blocks to provide procedural information. A task information type answers the "How do I?" question by providing precise step-by-step instructions detailing the requirements that must be fulfilled, the actions that must be performed, and the order in which the actions must be performed. The <task> topic includes sections for describing the context, prerequisites, expected results, and other aspects of a task."
- ACS Reference Topic
- Based on the standard DITA Reference Type. "Reference topics provide data that supports users as they perform a task. Reference topics might provide lists and tables that include product specifications, parts lists, and other data that is often "looked up" rather than memorized. A reference topic also can describe commands in a programming language or required tools for a series of maintenance tasks. Reference topics provide quick access to fact-based information. In technical information, reference topics are used to list product specifications and parameters, provide essential data, and provide detailed information on subjects such as the commands in a programming language. Reference topics can contain any subject matter that has regular content, such as ingredients for food in recipes, bibliographic lists, catalog items, and so on."
- Data Governance Reference Table Template
- Based on the ACS Reference Topic. This is a customized template built specifically for the ACS Data Governance Documentation project. The template may be adjusted for wider use. Contact the Content Lead with questions.
- Data Governance SQL Reference Template
- Based on the ACS Reference Topic. This is a customized template built specifically for the ACS Data Governance Documentation project. The template may be adjusted for wider use. Contact the Content Lead with questions.
- ACS Glossary Entry
- Based on the standard DITA Glossary topic. "Defining terminology in a glossary ensures that a team of writers uses the same term for the same concept. A glossary added to a book or available online in conjunction with other subject matter provides the reader with definitions of unfamiliar terms and expands acronyms."
- ACS Map (Ditamap)
- Based on the standard DITA map.
- Custom Sitemap
- This is a Heretto specialization that organizes a body of content for publication to the portal.Warning: If you are unfamiliar with working in the sitemap, contact the Content Lead. Avoid merging or replacing the sitemap in production without assistance and discussion. The sitemap can be quirky and it may require communication with Heretto when a large number of updates to the production sitemap are required. In other words, you don't want to do this on a Friday afternoon at 4:00 PM. :)
- Ditavals
- Use the DITAVal topic type. Ditavals are filters used to personalize content. Always begin a filter by removing all content
<prop action="exclude"/>.<val> <prop action="exclude"/> <prop action="include" att="product" val="PDS"/> </val>
Additional Content Types
- FAQ
- Use ACS Glossary Reference Template. Use FAQ's sparingly. Too many FAQ's can have a negative impact. An abundance is a likely indication that product content needs to be audited and revised, or is not tagged properly for search.
- Release Notes
- Use an ACS Concept Article. Images and media are encouraged to to make it more interesting and easier to scan. Individual feature enhancements should contain the following:
-
What is it?
- Why do I care?
- How do I find it?
-
- System or Browser Requirements
- Use an ACS Concept Article. We no longer publish minimum requirements. All system and browser requirements should be reviewed and approved by support.
- Third Party Equipment Topics
- Use ACS Concept, Task, and Reference articles as necessary. See detailed guidelines for authoring content about third-party hardware.
- Video Scripts
- Use Video Script topic type. See detailed guidelines for authoring video scripts. All video scripts are stored in Master > Video, then select the product folder you're authoring for. Access the Script Template
- Embedded Media
- Interactive PDF's, animation and video may be embedded as an <object> element. All video should be stored in Vimeo, which is the approved corporate channel. i.e. Youtube is not approved.
- Images
- Screenshots and informational graphics may be used. See style guidelines for additional recommendations.
- Micro-copy and System Emails
- Use an ACS Concept topic type to create individual file or a single "warehouse" of ux copy. For auditing purposes, we encourage the storage of micro-copy and system email copy in our CCMS. Rely on a combination of folder organization and taxonomy so this type of copy can easily be located and audited. Note: System emails that come from a church or parish should be concise and conform to a voice and tone consistent with church communication. 1
1 For reference, see Less Clutter. Less Noise by Kem Meyer