This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: Requirements Document - Markup?
- To: Megan Golding <mgolding at secureworks dot net>
- Subject: Re: DOCBOOK: Requirements Document - Markup?
- From: Michael Smith <smith at xml-doc dot org>
- Date: Tue, 19 Jun 2001 17:44:15 -0700
- Cc: docbook at lists dot oasis-open dot org
- References: <5.1.0.14.0.20010619112554.00a28800@atlexchange.secureworks.net>
Megan, you wrote:
> [...]
> What tags would you recommend for marking up a requirements document?
>
> [...]
> I considered using sections and lists, but didn't feel this solution
> was "right":
>
> <section>
> <title>Req't #1</title>
> <para>The software shall do....</para>
> <para>To test:</para>
> <orderedlist>
> <listitem><para>Send the 'foo' command.</para></listitem>
> <listitem><para>Look for appropriate output.</para></listitem>
> <listitem><para>Make sure things didn't
> break.</para></listitem>
> </orderedlist>
> </section>
Seems like if it's actually a procedure (set of steps), probably better to do:
<section role="requirementsection">
<title
>Foo must generate appropriate output without breaking anything</title>
<para role="requirement">The software shall do....</para>
<procedure>
<para>To test:</para>
<step><para>Send the 'foo' command.</para></step>
<step><para>Look for appropriate output.</para></step>
<step><para>Make sure things didn't break.</para></step>
</procedure>
</section>
Also, maybe lack of semantically-explicit "requirements document"
element names is part of what doesn't seem right, so you might try
using a Role attribute with something like "requirementsection" and
"requirement" values to distinguish requirement-sections and
requirement-paragraphs from normal sections and paragraphs.
And probably you don't really want to type "Requirement 1" as a title
in your source document. You can have requirement-titles automatically
numbered/formatted any way you want during processing, using a simple
customization layer to the modular DocBook stylesheets. So seems like
it's better to use a descriptive title; probably the title in the
above example is too long, but I'm sure you know what I mean
--Mike