This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: [docbook] Re: Task Markup (delinquent action item)
- From: Derek Dees <djdees at mm dot com>
- To: docbook at lists dot oasis-open dot org
- Date: Wed, 21 May 2003 11:51:34 -0500
- Subject: Re: [docbook] Re: Task Markup (delinquent action item)
- Reply-to: djdees at mm dot com
All -
I've been reading the notes, re Task Markup, and thought I'd toss my
$0.02 in.
I mostly use Docbook for constructing runbooks and build books for
setting up and running our e-business infrastructure in the data
centers. Using the task, prerequisites, procedure(s), and post
conditions would make my life a little easier.
To me, a procedure should be a list of steps to accomplish something
(e.g. a task), but a task includes additional information (e.g.
prerequisites, success criteria). Being able to tie together this
information would be useful to me. Adding the related information in
ulink or olink is a nice bonus. If task summary is included, I would
suggest that it be treated like abstract currently is and be available
both inside and outside of a taskinfo block.
Admittedly, I do all this now with sections, procedures and subtasks, so
not having it isn't very traumatic. However, from a lifecyle point of
view, it would make things much clearer for the poor saps stuck
maintaining my documentation after I've moved on to the next job or next
life.
I also think, having the structure in Tobias' message below would make
it easier to write XSL to generate check lists and other quick
references by providing some consistency in the structure that can be
used to our advantage.
Tobias Reif wrote:
> Adding precondition and postcondition could be handy for cases where
the task is to be carried out by software: Each task becomes a test case
which can be test automatically.
>
> <task>
> <title>Stripping Path Characters</title>
> <precondition>
> <programlisting>../foo./bar</programlisting>
> </precondition>
> <procedure>
> <programlisting>strip_path_caracters(string)</programlisting>
> </procedure>
> <postcondition>
> <programlisting>foobar</programlisting>
> </postcondition>
> </task>
>
> This is user documentation of a software task (what a specific
function/method does), not really modeling IMHO.
>
> Tobi
--
Derek
djdees@mm.com
http://www.mm.com/user/djdees
The follies which a man regrets most are those which he didn't commit
when he had the opportunity.
--Helen Rowland
---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org