[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: Requirements Document - Markup?
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
Powered by eList eXpress LLC