home

ACST Content Standards

RealmMinistryPlatformPDSACSAccountingGivingConnectShepherdGrowth MethodGo MethodMissionInsiteGatherHeadMaster ChildcareTrust CenterData Governance and Business DocsACST Content Standards
RealmMinistryPlatformPDSACSAccountingGivingConnectShepherdGrowth MethodGo MethodMissionInsiteGatherHeadMaster ChildcareTrust CenterData Governance and Business DocsACST Content Standards

What would you like to know more about?

Show Contents

thumbnailACST Content Standards

Our Content Model

The Task Topic

Task topics are the most important part of a help system because tasks helps users accomplish real-world goals. A task topic answers "How do I....?

Task topics provide step-by-step instructions in the order they must be performed in.

Title Guidelines

  • Naming standard: t_product_name.dita.

  • Use title case

  • Begin the task with an verb.
Examples "Request a Trial Account", "Personalize Your Public Site".
Note: The DITA task topic is documented at docs.oasis-open.org.

Style Guidelines

  • Separate task information from conceptual 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. See Oxygen's article, "Avoiding chunk structure in topics".
  • Write one task per topic.
  • Create tasks and sub tasks to organize long procedures.
  • Are there required steps or actions to take after this procedure?
  • When writing steps, ask yourself if the user needs examples or images to complete each step. However, due to long-term maintenance of content, only include images in the steps when the user interface changes as a result of the step or if the step is overly complex, field labels are not friendly, or you are aware of data or concerns from support that the steps frequently confuse customers. This includes known usability issues.
    • To insert an image during the step, wrap the image in the <info> element.
    • To insert an image with completed fields or selections, use the <stepxmp> element.
    • To insert an image of the interface after completing the step, use the <stepresult> element.
  • If a user must select from multiple options, use a <choicetable> below the step.
  • When tasks require reference material held in definition lists, charts, graphics, or lengthy tables, place the information in a reference topic and chunk to the task topic.

Structure

Task elements are documented at dita.oasis.org. See also Oxygen's documentation.

<title>
Task title. Use title case. Begin the title with a verb.
<shortdesc>
Introduce the task in the short description, but refrain from writing sentences like "You can..." or "Staff can...".
<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".
<taskbody>
The taskbody is the main body element that contains the elements below.
<prereq>
Is there information or are there permissions the user needs in order to complete the procedure? Place this information in the <prereq> element. If there's more than one, add requirements in a <ul> (bulleted) list.
<choices><choice>
Use to indicate 1 - 2 choices. Does the user have choices to make? If so, wrap each choice in a single <choice> element. (Note: <choicetable> displays choices in two-column table where you an describe steps for each choice. May not have CSS for this element.)
<choicetable>
Used to contain 3 or more choice.
<context>
What circumstances requires the user to complete the step. Conversely, when does a user NOT need to complete a procedure? For example, a user does not need to integrate their ChMS if there is no need to synchronize information between it and a stand-alone application like Go Method.
<steps>
Contains all of the step elements.
<step>
Contains a command element that describes an action and other elements that help you perform the action. Communicate each step clearly, using active voice. Optimally, limit the number of step elements to 7 (+/- 2) per task topic.
Note: To make a step optional, set the step attribute Importance field to Optional. This puts the word "Optional:" before the step in the portal.
<cmd>
Describes a single action that must be taken. Write clearly, use active voice. Write in the imperative. Example: Insert the lined baking tray in the oven.
<info>
Clarifies a step or provides more information about the step. You can use this element to insert an <image>, <codeblock>, or <note>.
<stepxmp>
Use when an example is required to complete a step (such as an image with completed fields).
<substeps>
Add sub-steps required to complete a step.
<stepresult>
Is it important for a user to know the expected results of a single step? If so, insert in this element. You can insert an image in this element.
<result>
Describes the outcome of the entire task or procedure.
<postreq>
If the user must test for success or meet other requirements after completing this step, enter the requirements here.

Last updated: March 3, 2026