DOCBOOK: New Element Task Proposal

[Sabine Ocker - Sun Microsystems <Sabine.Ocker@Sun.COM>]

This is my second post recently to the Docbook mail-list. Thanks very 
much to those who took the time to respond to my first posting on 
the Step Alternative proposal. We use the SGML version of the 
Docbook DTD.

Writers at Sun Microsystems have had a long standing need to be able
to have information which relates to Steps in a Procedure. 
Research into our current documentation has revealed that the ancillary
material takes the form of:

* Examples
* Links to related information
* Other similar tasks
* Troubleshooting tips

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 to use correctly and difficult for our tools to output correctly. 

Further investigation of the use of Procedure markup in our documentation
revealed most consisted of these categories of data:

* An optional, brief introduction
* Optional prerequisites
* The steps in the procedure
* Related information

We found that for us, Procedures are more of a container-type element than
a list-type element. Rather than try to revise Procedure to contain all these 
pieces of information, we've devised what we think should contain a Procedure,
a new element data model we call Task.

Based on our needs, we feel there a need for a new hierarchy of markup in 
Docbook, and have drafted a proposal for Task. Please let us know if you have a 
similar requirement for your software documentation, and make suggestions
of other ways you might see us meeting our requirements for an easy, clear
methodology for referencing and reusing Procedure related information.


<!ELEMENT Task - - ((Title,SubTitle?,TitleAbbrev?),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,SubTitle?,TitleAbbrev?)?,(%component.mix;)+))>

Brief description of the function of each of the new elements:

Task: Is a titled container for all specific pieces of information
related to Procedure--or the more generic Tasks. The specific hierarchy
as requiring specific markup makes Task similar in design 
to QandASet or SimpleMsgSet. Since related data is kept together, in addition 
to a consistent tagging methodology, this also allows for clear 
cross-referencing, 
collapsing or reuse. Task data could also be used for online Help. Is a peer to
Sect2,3 and Sect4.

TaskAbstrast: Short description or summary of the Task. Information
which writers want readers to know about the Procedure which follows it.
This information is similar to available markup before the 
Step in the current Docbook Procedure content model.

TaskPreReq: Any specific, identified, conditional information which is required
prior to completing the steps in the Procedure. This information is most likely
to take the form of an ItemizedList.

Example: Already a Docbook element.

Procedure: Already a Docbook element. 

RelatedInfo:  Titled container for the ancillary information types I mentioned 
above. We'll use ROLE attribute to generate title text of "Examples," "Where to 
go for 
more Information," etc.  Will be included in TOC, as well as List of Examples.

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>

Thank you for your consideration.
regards,
Sabine Ocker