"Standard" program documentation?

E

Ed Kirwan

Hi, folks,

Does anyone know of a, "Standard," way to document software?

Perhaps I'm a dinosaur, but I find a text description is the easiest way
to start understanding code. This text description will ideally explain
the overall system and perhaps some key issues (concurrency, why certain
design decisions were made, etc.) in a few pages (say, less than 30);
after this, I find sequence diagrams (and to a lesser extent, use case
scenarios) to be the next useful way to see more detail.

I find class diagrams to be more of a reference than a self-contained
means of understanding a system's behaviour.

As far as I know, Rational's 4+1 view is a relatively widely-accepted
means of describing a system (architecture); though this tends, I find,
to go straight into the details rather than giving that 30-page overview
previously mentioned.

Of course, there's always Javadocs; but again, these are pretty
detailed, and as far as I'm aware there's no natural place to put a
system overview (I think there highest level descriptions are
package-level, though I haven't checked in a while). And in any case,
objects should never describe who their users are (they should never
care), so code comments tend to describe objects more or less in
isolation: great for API users, not so great as a starting point for
understanding a system.

(JavaHelp is for system users; I've not seen an example of JavaHelp
explaining system behaviour.)

Perhaps I'm just stuck in the past, and am too familiar with text
overviews to appreciate that such overviews are more well-suited to use
cases (or some such other documentary means). So how about a follow-up
question: does anyone know of any good program descriptions on the web?

I've googled for, amongst others, "Program description," and, "Program
documentation," but haven't come up with anything illuminating.

(Of course, many will say, "The code is the documentation;" to these I
say, "Here's 100,000 lines of code, prepare a summary of behaviour in 24
hours," and compare their conclusions with someone who has read a
30-page text overview.)

Tack så mycket ...
 
D

Doug Schwartz

Documentation is typically built from the bottom up. Reference first, then a
user's guide, then overview material as the author becomes more familiar
with the system. I started with the Unix Programmer's Manual, volumes I and
II in my first gig.

The overview should always include at least a block architecture diagram.

I am also a big fan of cookbook sections in the user's guide. Pick the six
to ten most common/important tasks that almost every user needs to
accomplish and walk them through. These are very similar to a tutorial,
although not exactly the same as they need not build upon each other, as a
tutorial should.

HTH,

doug
 
C

Chris Uppal

Ed said:
Does anyone know of a, "Standard," way to document software?

Perhaps I'm a dinosaur, but I find a text description is the easiest way
to start understanding code. This text description will ideally explain
the overall system and perhaps some key issues (concurrency, why certain
design decisions were made, etc.) in a few pages (say, less than 30);
after this, I find sequence diagrams (and to a lesser extent, use case
scenarios) to be the next useful way to see more detail.

I don't know of any. To an extent there probably coudn't be a "standard" for
overview documentation -- almost by definition the requirements (and hence the
contents) are going to be different each time.

I agree that such documentation is valuable -- very much so. It seems to me
that the problem of what to write, and how to write it, is particularly acute
with OO systems. If an application (or to a lesser extent) a library really is
the famous "ecosystem of communicating objects" then it's hard to pick out the
main themes. That's especially true if the overview is written by the
designer/programmer because it's hard for them to let go of the details and
just give the broad outlines.

As something of an aside, I want to state my dislike of diagrams. Not only do
I, personally, not think visually, but it seems that few programmers are
capable of the abstraction necessary to produce /helpful/ diagrams. There's
the detail problem again, but also (in my experience) programmers want to put
features which belong at different levels of abstraction into the same
diagram -- which is a category error.

Another problem is layering. Most significant systems use software layering,
and that tends to cross-cut the "ecosystem of communicating objects" aspect,
which makes it even harder to state the broad sweep. (And there's the risk of
category errors too.)

One approach which I like in theory, but have had only middling success with in
practise, is to give two views of the system. One a description of the
layering. The other a description of the main players in the community of
objects -- the Dramatis Personae of the unfolding drama, as it were.

Somewhat hesitantly, I'll mention one attempt I've made along those which is
available on the Web. It's part of the documentation for a package of mine,
called JNIPort, which is a bridge from Dolphin Smalltalk to Java, linked via
JNI (Smalltalk is the master, Java the slave). I definitely do /NOT/ claim the
attempt as an exemplar (let alone a "standard") for overview documentaton. I
consider it closer to a failure than a success. But it may be an interesting
failure ;-) If you are interested see "Layers" and "Players" which are linked
to from:
http://www.metagnostic.org/DolphinSmalltalk/JNIPort/overview.html


Of course, overviews (however constructed) are only part of decent intoductory
documentation. There's also (usually) the need for introductory examples of
both installation and use; cookbook examples (howtos); tutorials; and so on.

-- chris
 
T

Thomas Weidenfeller

Ed said:
Does anyone know of a, "Standard," way to document software?

"The nice thing about standards is that there are so many of them" ...

Almost every software engineering method or process comes with come kind
of definition for some kind of standard documentation. Typically, the
required scope, level of detail, contents, etc. varies greatly.

You also have stand-alone standards/guidelines from various
standardization organizations, e.g. stuff like ISO/IEC 6592:2000
"Information technology. Guidelines for the documentation of
computer-based application systems."

Also, big organizations set their own standards, depending on their
requirements. E.g. these guys have very special requirements:
NASA-STD-2100-91 http://satc.gsfc.nasa.gov/assure/docstd.html

On a different level you have stuff like coding standards for particular
languages. E.g. organization-specific
(http://www.gnu.org/prep/standards/), or more or less as de-facto
standards for a particular language
(http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html).

So, what type of standard are you after?

/Thomas
 
D

Dale King

Doug said:
Documentation is typically built from the bottom up. Reference first, then a
user's guide, then overview material as the author becomes more familiar
with the system. I started with the Unix Programmer's Manual, volumes I and
II in my first gig.

The overview should always include at least a block architecture diagram.

I'm not sure I agree that documentation is typically built bottom-up. I
have come to the conclusion that there are people that learn things best
from a top-down approach and those that learn things best bottom up.

From the many documents that I have read that were written from a
top-down style and I had difficulty understanding I have learned that I
am definitely discovered that I am a bottom-up person. The problem with
top-down is that you are introduced to a whole bunch of things without
any detail.

But I think some people have trouble with bottom-up. They probably have
trouble learning details without having the broader context in which to
place it.

I'm sure an education person could expand on that further.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,483
Members
44,901
Latest member
Noble71S45

Latest Threads

Top