RE: DOCBOOK: Docbook, UML and Test

["Donna K. Kidwell" <donna.kidwell@athensgroup.com>]

Hello Norman,

I've got a large word document that I'm marking up in Docbook so that I can
make the document modular and more flexible.
Much of the document (20 pages at a time) are currently embedded in Word
tables.  The tabular format is solely for the purposes of formatting, but
there is a consistent data structure within them.  I would like to have the
content self defining, and toss transformations together that will present
the data in various forms throughout the manual.

One chapter of the document includes use cases and other chapter contain
communication sequences.  I've got two primary forces encouraging small
custom DTDs:

1. If I build a robust enough method for marking these up, I can build
repositories, over time, of use cases and sequences across projects. We're
software engineers, and the thought of having a library of these spanning
projects of various sorts would make for some very easy assets mining later
on.

2.  Small, simply marked up files will be easier to wrangle for the
development team.  I'm more likely to get the programmers on my team to deal
in an intuitive DTD, than I am to get them to use CALS tables. I could ask
them to understand and look at docbook a bit closer, but it's already hard
just getting them to document things, much less mark them up.

For the use cases, I'm currently knocking around something like this:
<!ELEMENT UseCase (name, description,
    actor+, precondition?,note?, interaction+)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT actor (#PCDATA)>
<!ELEMENT precondition (#PCDATA)>
<!ELEMENT note (#PCDATA)>

<!ELEMENT interaction (actionid+, action+, response+)>
<!ELEMENT actionid (#PCDATA)>
<!ELEMENT action (#PCDATA)>

<!ELEMENT response (responseid+, responsedesc+)>
<!ELEMENT responseid (#PCDATA)>
<!ELEMENT responsedesc (#PCDATA)>

I could use attributes on existing docbook elements to identify these, but
that doesn't ease the resistance from the coders.

Got any ideas for me?
Thanks!
Donna

-----Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com]
Sent: Thursday, April 05, 2001 10:33 AM
To: docbook@lists.oasis-open.org
Subject: Re: DOCBOOK: Docbook, UML and Test


/ "Donna K. Kidwell" <donna.kidwell@athensgroup.com> was heard to say:
| Cases included in the final documentation set.  I'm currently using
Docbook
| for the manual,
| but use cases and test cases don't map to Docbook very well.  I'm

In what way do they not map well? Can you describe some specific problems
that you've encountered?

                                        Be seeing you,
                                          norm

--
Norman Walsh <ndw@nwalsh.com>      | A moment's insight is sometimes
http://www.oasis-open.org/docbook/ | worth a life's experience.--Oliver
Chair, DocBook Technical Committee | Wendell Holmes

------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org