Documentation standards

[wakeland@ccgate.leupstv.com]

Toms suggestions regarding better documentation support within the
software packages sound good to me!

Heres what I do whenever I work on a model. I have a Word document
open that is based on a template developed by Ed Gallaher called
"Instant Manual." I toggle back and forth between STELLA and Word
documenting my thought processes and assumptions. I also frequently
clip diagrams, portions of diagrams, and plots into the document. I no
longer build models any other way.

I have noticed that for a given computer "session," I spend about 3/4
of my time in Word and 1/4 of my time in STELLA. This doesnt mean it
takes me 4 times as long to complete a project. In fact it may take
less time overall. But it certainly assures that I have documented
what Ive done. This often did not occur in the past.

Wayne Wakeland (wakeland@leupstv.com)
Adjunct Assoc. Prof.
Systems Science Ph.D. Program
Portland State Univ.
P.O. Box 751
Portland, OR 97207

[Bill Harris]

Wayne Wakeland wrote:

> Heres what I do whenever I work on a model. I have a Word document
> open that is based on a template developed by Ed Gallaher called
> "Instant Manual." I toggle back and forth between STELLA and Word

It seems to me I saw that template on the mailing list previously, but I
must have not saved a copy. Is that available for distribution?

I agree about the utility of integrating the model and a textual
description; it sort of sounds like Knuths literate programming applied to
SD.

Thanks,

Bill


--
Bill Harris Hewlett-Packard Co.
R&D Productivity Department Lake Stevens Division
domain: billh@lsid.hp.com M/S 330
phone: (206) 335-2200 8600 Soper Hill Road
fax: (206) 335-2828 Everett, WA 98205-1298

[tomfid@MIT.EDU (Tom Fiddaman)]

A while back, Stever Wehrenberg asked me whether I knew of any utilities
that could link a set of documentation (in a word processor or database)
with a model. I didnt have an answer for him, but the question got me
thinking about what really ought to be built into our software (or the
heads of practitioners) to facilitate the creation of comprehensible and
replicable models. My thoughts on the matter follow. Id be interested to
hear what anyone else thinks!

- Tom Fiddaman

------------------------

SD has always had high standards for documentation. The DYNAMO documentor,
for example, supported extensive cross-referencing of equation listings
more than 20 years ago.

Documentation is a lot easier if you do it as you go. Dennis Meadows taught
me to keep a lab notebook around when working on models, for recording
assumptions, problems, insights, etc. I think he got that habit from Jay
Forrester.

STELLA used to have a nice feature called the "journal", which was just a
listing of the equations that had been changed since the last time the
journal was cleared. This was really useful for seeing what youd done at
the end of the day. I dont know why the feature was dropped. Vensim
provides a similar capability through the "history" feature of the text
editor; unfortunately it doesnt work when you mix graphical and text
editing.

I tend to put a lot of material in the Vensim or ithink documentation
field, though it would be nice if there were some way to structure the
documentation better. Theres always plenty of short term pressure to skip
documentation, so it needs to be as easy and habitual as possible.
Specifically, Id like to have the following:

- units
- a field for equation documentation that would be seen by a model consumer
(the user of a flight simulator, for example)
- a second field for my worries, speculations, navel ruminations, etc. that
Id like to keep in the model, but hide from the casual user.
- an automatically-date-stamped field for documenting changes made to the
equation. If any developers are reading, they might look at the notes field
in TouchBase (a personal information manager).
- a check box that allowed me to indicate equations that I need to
reexamine at some point in the future

It would be useful to have similar information that would help one to
document simulation runs, internally consistent sets of parameters, etc.

The difficult part of documenting a model is not so much at the equation
level, though. Identifying and describing important subsystems or feedback
loops is crucial, but I think the current approaches to documentation at
this level are much more of an art than a science. I wonder whether it
would be possible (or fruitful) to create software support for the
documentation of models at these higher levels of abstraction.

______________________________________________________________
Thomas Fiddaman, PhD Candidate http://web.mit.edu/tomfid/www
MIT Sloan School of Management, System Dynamics Group
E60-355, 30 Memorial Drive, Cambridge, MA 02142
MIT: 617-253-3958 home: 603-497-2273 email: tomfid@mit.edu
______________________________________________________________

[jimhines@interserv.com]

Some more ideas about documentation:

1) The journals I keep (now they are now word processor documents, using lots
of cut and paste) are very heavy on showing behavior; hypotheses (usually loops)
about the causes of the behavior; and tests of the hypothesis (which produce
more behavior and more hypotheses). This style is like a depth-first traversal
of a graph. The ability to keep track of this depth-first traversal (as well as
an easy way to record behavior and hypotheses) would be very handy.

2) Some software development environments have very good version control. I am
familiar with Visual Smalltalk Enterprise. Past versions are all saved.
Interestingly the prior versions take up very little disk space (somehow the
version control software must be saving only the DIFFERENCES; and those in very
compressed form). There seems to be essentially no cost to saving a new
version; along with annotations about the new version. Old versions can be
easily resuscitated. Its amazing.

3.5) Along with version control; software development environment like VSE make
it easier for a team to work on a software product. The version control makes
it possible to "mix and match" modules from a central library. Different people
can be working on the different modules. I dont think it would not be as easy
to create an SD-flavor of team-management as it would to create an SD-flavor of
version control.

3) Vensims feature of checking units is EXTREMELY valuable for catching
conceptual errors quickly.

4) A model can be written in Vensim, iThink, and Powersim in a style that
requires almost no equation-level documentation (except for units). For this
one needs to use self-explanatory variable names and lots of auxiallaries.
(DYNAMOs problem is that it is still restricted to 8-character variable names,
I believe). Basically, what is needed here is probably a manual of style,
rather than software.

5) It would be nice if one could create little notes and comments right on the
diagram (Vensim, iThink, Powersim) that easily can be hidden (like the
annotation feature in Microsoft Word). For example, itd be nice to be able to
circle a stock and write the comment: "no first order control".

6) There is an order of listing equations that used to be followed in the old
days. It would be nice if there were an automatic way to generate this order of
equation. (Segmented by view (Vensim), goup (Vensim), or sector (iThink)).


Regards,
Jim Hines
jimhines@interserv.com
LeapTec and M.I.T.

[David Bridgeland]

Powersim 2.5 supports OLE 2.0, the Microsoft Windows standard for linking
and embedding objects within other applications. For example, you can embed
a Powersim model --- or part of a model --- within a MS Word document. It
can even be simulated from within Word. This makes possible a rich
mechanism of documenting the modeling process.


Dave.
David Bridgeland
davbr@powersim.com
Powersim Corporation
Herndon, Virginia
www.powersim.com