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
