[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: Marking up task-based information
Sun Microsystems has proposed a model for tagging task-based information to the DocBook Technical Committee. The TC has requested input from the general DocBook community before the proposal is discussed. Your feedback would be immensely helpful to us. Writers at Sun have had a long standing need to be able to include related information with procedures in our documentation. Until now, we've used a clunky workaround that has proved to be quite problematic. The current DocBook markup does not allow for any additional, related information to exist within a Procedure after Step. In the past, we've worked around this limitation by using the ROLE attribute on Sect2 to indicate that the Procedure had "other stuff," but we've found over time that having two different methods for marking up Procedures is confusing to writers -- leading to incorrect usage -- and difficult for our tools to output correctly. We've identified the need for a more structured model we're calling Task. A task contains the following kinds of information: * A brief introduction/description that frames the context of the procedure * Prerequisites * Procedure (steps) * Examples * Related information All of the information blocks other than Procedure are optional and need not be included in every task. The "related information" category is usually pointers to reference information related to the task, troubleshooting information if the procedure didn't work, or the next steps the user should take after completing the task. We're proposing to the DocBook community that a new model called Task be created. The syntax below represents the model. Following the element declarations are descriptions of the intended purpose for each element. If you have suggestions, dissensions, or comments, please direct them to me (as well as the entire list) and I will gather the feedback for a report to the TC. Thank you! Thank you! Steven Cogorno Sun Microsystems, Inc. ________________________________________ <!ELEMENT Task - - (Title, IndexTerm*, TaskAbstract?, TaskPreReq?, Procedure, Example*, RelatedInfo*))> <!ATTLIST Task %id.attrib; %lang.attrib; %remap.attrib; %arch.attrib; %os.attrib; > <!ELEMENT TaskAbstract - - (%component.mix;)+)> <!ELEMENT TaskPreReq - - (%component.mix;)+)> <!ELEMENT RelatedInfo - - (Title, (%component.mix;)+))> Task: Titled container to contain information related to the task. Using a new container permits related data to be kept together. This allows for clear cross-referencing, collapsing or reuse. Task data could also be used for online Help. Is a peer to Sect2, Sect3 and Sect4 and can be intermixed with those elements. TaskAbstrast: Short description or introduction to the Task. This element contains a description of the procedure or other information that gives context to the task. This element is optional. TaskPreReq: Requirements that must be met before attempting the task. Prerequisites include: - knowledge the user should have before starting - precautions the user should take (backing up, turning off power, etc) - other tasks that must be completed before this task This element is optional. Procedure: Already a DocBook element -- unchanged. Example: Already a DocBook element -- unchanged. RelatedInfo: Titled container for the ancillary information. Types of related information include: - section describing where a user can find reference information that further explains the steps in the procedure - actions to take if the procedure didn't work - other tasks that relate to this task Example Markup: <task id="foo-123"> <title>To Notify Users When a Host or Agent Is Down</title> <taskabstract> <para> By default, the software checks whether a host or agent is not responding. However, there is no default action defined in response to these conditions. The following procedure explains how to define an email to send when this condition occurs. </para> </taskabstract> <procedure> <step> <para> Select the managed object on which you want this action performed. </para> <tip> <para> To apply this action to all children of a managed object (to all objects within a particular subnet, for example), select the parent managed object (in the example case, the subnet). </para> </tip> </step> <step> <para> Press mouse button three and choose Alarm Action from the pop-up menu. </para> <para> The Alarm Action window appears. </para> </step> ... <step> <para> To complete the alarm action definition and exit from the Alarm Action window, click the OK button. </para> </step> </procedure> <example> <title>User Notification Action</title> <para> The following example shows a completed user notification script. </para> <screen> email.sh: horatio.alger@sun.com "Systems down. Call Stuart." </screen> </example> <relatedinfo role="see-also"> <para> Related information is contained in the following sections: </para> <itemizedlist> <listitem> <para>Sending Email </para> </listitem> <listitem> <para>Schedule Action </para> </listitem> </itemizedlist> </relatedinfo> </task>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC