Re: DOCBOOK: Requirements Document - Markup?

[Michael Smith <smith at xml-doc dot org>]

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