This is the mail archive of the mailing list for the DocBook project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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

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



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: For additional commands, e-mail:

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]