Re: [docbook] Re: Task Markup (delinquent action item)

[Derek Dees <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