Re: Sample software requirement docs <DID>

[Ned Bedinger <nbedinger -at- USWEST -dot- NET>]

Smokey Bare asked:
> <snip>...in the process of replacing their Database 498 DID with the
>design segment in IEEE/ISO 12207.
<snip>
>What they need now is to see a sample of this type of documentation in
>this format.  They have nothing to go by, as there is NO documentation
<snip>
>Application development is looking for a sample that has detailed
>requirements, something a programmer can actually program from.  This is
>also to be used as an example for the functional people <snip>

I did a little background research to get up to speed on your question, and
I'll recap it to make sure we're on the same page.

When you say there is no documentation, it looks like that is the idea
behind 12207--it is a high-level overview that intentionally leaves the
design process content and methodology open. This is the kind of thing that
has to be done to accomodate modern development environments, especially
object oriented devlopment.  I hit a few 12207 web sites, and found one
that talks about this.
http://www.stsc.hill.af.mil/crosstalk/1996/aug/isoiec.html

Two quotes from this site:

"ISO/IEC 12207 says in paragraph 1.5 that it "describes the architecture of
the software lifecycle processes but does not specify the details of how to
implement or perform the activities and tasks included in the processes.
...  Here is an example: MIL-STD-498 and its DIDs contain 117 pages of
engineering and data requirements related to MIL-STD-498 activities that
correspond to the development process in ISO/IEC 12207, which contains less
than seven pages of requirements on that process. "

"In paragraph 1.5, ISO/IEC 12207 states that, "this international standard
does not prescribe a specific lifecycle model or software development
method." In language similar to that in MIL-STD-498, paragraph 5.3.1.1
states that unless the contract stipulates one, "the developer shall define
or select a software lifecycle model appropriate to the scope, magnitude,
and complexity of the project. The activities and tasks of the development
process shall be selected and mapped onto the lifecycle model." The intent
and effect of the language in the international standard are to provide
flexibility in ordering activities, and to choose development models to
avoid the waterfall bias of ther standards. "

So, by my reading, ISO 12207 is unlikely to be highly specific even about
DID. Another quote addresses this nicely:

" ISO/IEC 12207 ... has no data item descriptions (DIDs)."

Obviously, you need data descriptions if your software handles any data.
The net effect of your task will apparently be to take DIDs from existing
docs (or write new ones) and dump them into some new format to be
determined by whoever develops the design specs.  As far as I can tell, you
could keep whatever DID has been in use. I don't get any sense of the DID
being an issue that was addressed by ISO 12207, so why not just lift it
from MIL-STD-498 or some familiar source?

----------------------------------------------------------------------------
Side note about owning the data dictionary and what the DID means to you:
----------------------------------------------------------------------------

The more effort you get on the DID from the designer at this stage, the
better off you'll be when you document the data for the end-users,
analysts, data entry people, etc. If you do a thorough job as you go, you
can avoid problems later.  There is nothing that prolongs the doc project
like having data designers move on to new projects before you're finished
picking their brains.

Some groups I've worked with in the past (not mil, sorry) expect a tech
writer to own the data dictionary and maintain it. The obvious requirement
if you own it is to capture the data desciption that will satisfy
developers and end-users.  Design the DID with that principle, because
you'll have to gather that info eventually even if you don't own it now,
since you're documenting it. You definitely need to weigh in on the DID
design so that your info requirements (presumably something to do with
publishing a data dictionary to the end-users) are built into it, since
you're probably the only one thinking about that at this point.

The data dictionary is pretty deep stuff for the tech writer to own, made
possible largely by the fact that you're in the project at its inception,
and you can try and get the developers to do a matrix of each data item
(table names, table descriptions, data item name, table it resides in, data
type, where it is used--what queries use it, etc.) for you as they go.


Hope this helps


Edward Bedinger
Technical Communications
Edword Co.
206-782-0378

---------------------------------------------------------------------------
If this were merely my opinion, I'd probably keep it to myself.
My employer is not responsible for my expressions.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=