Re: software systems documentation

[Anthony Markatos <tonymar -at- HOTMAIL -dot- COM>]

Rebecca Price asks:

a co-worker has the assignment to locate standards for documenting
software.. not from the user's end, but from the point of view of the
person who has to update it years later.  I know from a job several
years ago that there do exist some standards, but I can't remember
from where we got them or what they were.

(the co. I work for is *trying* to get ahold of it's processes, rather
than doing everything on an ad hoc basis.  noble cause, but lots of
hard work for all concerned.)

if you can give us any guidance, please send notes to
jboylan -at- umich -dot- edu -dot-   Thanks!



Tony Markatos responds:

A key concept to keep in mind when documenting software for
maintainability (or for any other purpose for that matter) is that
systemtaic documentation of WHAT the software does from the end user's
perspective provides the framework upon which all other documentation
hangs.  In other words, if we want to capture both WHAT the software
does and HOW it does it, we must first capture the WHAT and then base
all the HOW around it.

Often, documentors will forget about the WHAT and jump right into the
HOW.  This is unfortunate, especially for people who come on board in
the future to maintain (or build upon) the existing software.  I've been
there many a time: trying to use existing documentation that goes
on-and-on about HOW something works but gives only a very vague idea of
WHAT is being done.  Real hard stuff to use.

Best tools?  For clarity and conciseness, there really is no substitute
for Data Flow Diagrams, a Data Dictionary, and (to the degree necessary)
Entity Relationship Diagrams.  Properly employed, these tools create
documentation that can be easily understood by anybody with a high
school education.  *Now thats technical communications!!*

Many people try to document software systems using just logical type
flow-charts.  However, these tools were designed to capture the HOW and
not the WHAT.  Also, logical flow-charts, along with text, lists, and
heirarchtical type tools, are meant to document sequential (i.e., one
thing happening at a time) procedure.  Software systems (especially
larger ones) are very asynchronous (i.e., there is no set sequence -
different functions can be envoked at different times).  Only the tools
mentioned in the prior paragraph capture asynchronous procedure.

Tony Markatos

______________________________________________________
Get Your Private, Free Email at http://www.hotmail.com