OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[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*))>
<!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>
	 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.
         Select the managed object on which you want this action performed.
         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).
         Press mouse button three and choose Alarm Action from the pop-up menu.
         The Alarm Action window appears.
         To complete the alarm action definition and exit from the Alarm Action window, click the OK
   <title>User Notification Action</title>
	 The following example shows a completed user notification script.
   email.sh: horatio.alger@sun.com "Systems down. Call Stuart."
   <relatedinfo role="see-also">
      Related information is contained in the following sections:
	    <para>Sending Email
	    <para>Schedule Action

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC