Can You Show Me How to Do This?
by Doug Williams
Someone asked me today how to deal with presenting a series of examples to a user to help them complete a task. The information wasn’t a concept. It wasn’t a steps procedure. What was it? Maybe just a generic topic? That prompts me to write about this kind of information typing issue, because I think it is a common one, and in the future, maybe I can point to this post.
When we were creating our DITA templates, our answer for this information typing question was to produce an informal task template, which we called a “Task Code Example,” after what we expected would be the typical use case. Though you might not realize this by reading the OASIS DITA standard, the task information type doesn’t require that you make every task a step procedure. In real life, you very commonly show someone how to complete their task by giving a scenario context, and then provide a series of screenshots or command lines to show how you complete a task. We wanted a standard format for creating such example procedures.
As with a formal task or an informal ordered list task, the Task Code Example information type answer the “How do I?” question by providing step-by-step instructions that provide details about the requirements that must be fulfilled, the actions that must be performed, and the order in which the actions must be performed. It’s just that instead of describing steps, or provide detailed steps, informative side comments, and maybe also examples, you just provide examples. This format is particularly good when the task is only entering a few commands, or a screen input or two, so the examples you show are relatively simple. As with the strict task, you can provide context and prerequisite sections. You can also put these information units inside formal example elements, so that they can be made more visible to users–but if more than two or three, then you really should consider separate task code example topics. Section and example elements, you should remember, are not hierarchically determinable, and so if someone needed to navigate through a bunch of them, then that is an accessibility concern. The unit of information for a user should be a topic, not sections or examples in a topic. If your procedure consists of individual examples that could be reused in another example context, then definitely create separate task code example topics, and combine them together under a common orientation/container topic that sets the context for this particular scenario, and that provides your user with an Autogen link list they can use, particularly if they need to refresh their memory about a procedure. Scanning a link list for a reminder of that task you half-remember, and clicking directly to the one for which you need a refresh, is far better than wading through a topic of 20 examples. And–accessibility again–never link back and forth between sections and examples.
Here’s the basic structure of a task code example topic type.
<task>
<!--Use for a task topic where the how-to info is a code example, not steps.-->
<title>Task Code Example</title>
<shortdesc>
<draft-comment>(Required) Enter a short description of the task here. This short description displays as the first part of the topic and also displays as a link preview to the topic.</draft-comment>
</shortdesc>
<taskbody>
<context>(Optional) Enter contextual information here, including the purpose of the task.</context>
<example>
<title><!--If more than one, then typically use titles with examples--></title>
<p>(Optional) Introduce the code example. We envisaged usually a set of command prompt command line entries, such as this: </p>
<codeblock>
$ cd Grid_home/bin
$ ./asmca
</codeblock>
</example>
<!--Add additional examples here-->
</taskbody>
</task>