NetNews Usenet Archive 1992 #30/NN_1992_30.iso/spool/comp/lang/fortran/4682

Internet Message Format | 1992-12-18 | 4.1 KB

Xref: sparky comp.lang.fortran:4682 comp.lang.c++:17875 comp.lang.c:18269
Path: sparky!uunet!cs.utexas.edu!bcm!bcm!usenet
From: [e-mail] (Richard H. Miller)
Newsgroups: comp.lang.fortran,comp.lang.c++,comp.lang.c
Subject: Re: Examples in Documentation
Date: 12 Dec 1992 21:40:25 GMT
Organization: Baylor College of Medicine, Houston, Tx
Lines: 63
Message-ID: <[e-mail]>
References: <[e-mail]> <[e-mail]>
NNTP-Posting-Host: crick.ssctr.bcm.tmc.edu

In article <[e-mail]>, [e-mail] (der Mouse) writes:
> In article <[e-mail]>, [e-mail] (Douglas Rosener) writes:
>
> > How important are examples to you when you are looking up a function
> > or syntax in a reference manual.
> [I assume the period is supposed to be a question mark.]
> > Are they unnecessary, essential, or somewhere in between?
>
> It depends largely on whether I'm using the manual as reference or
> tutorial.  When using documentation for reference, I rarely have any
> use for examples, but when using it to learn things, they are helpful.
> *How* helpful they are depends on (a) how well-written the rest of the
> documentation is and (b) whether they are correct.  (The latter may
> seem obvious, but I've seen far too many manuals with code examples
> that obviously wouldn't even compile, much less work.)
>

And this is the problem with trying to have a single manual serve both as
reference and tutorial. (Actually there is a third class I would call
'cookbook' which is between the tutorial manual and the reference manual.
I view documentation for the programmer as existing on these three levels.

1) A reference manual - This contain all of the information required to
use the product being documented. It will contain explainations of all of
the constructs, their use and all options as well as return codes and the
like. Examples would not appear in these books except as part of the
documentation of use.

2) The tutorial manual - This is a manual which is used to tutor a person who
is not familier with the product to gain sufficient proficiency in it to
understand the reference manual.

3) The 'cookbook' manual - this would contain the examples on how to use the
product demonstrating several of the uses of the product with real-life code.


To use an example, please excuse me for getting away from the strict charter
of the groups and use an example from our shop. We have a Unisys 2200 and
part of what we do is develop TIP transactions using COBOL. (Please no
comments about the appropriateness of the language; for TIP programming
COBOL is the route we use.) Unisys provided a programmers reference manual
which documented all of the features required to program TIP transactions as
well as a tutorial on what TIP was. There were some simple examples in the
tutorial of transactions but no examples of some of the more complicated
things which transaction do. We have complained about this for years and
finally Unisys has started providing this cookbook manual which contains
many examples of how to do some of the more complicated things. Thus with the
three manuals, we can finally provide an applications programmer with the
necessary documentation to allow them to write code. (It used to be the practice
to call up other sites or talk with them at USE and glom some code of things
you needed.)

One other point, electronic documentation is great for reference manuals but
there will always be a need to paper manuals especially when one is developing
some of these more complicated things. It is easier to have that manual open
and be able to flip it depending on how things do, It is also useful to have
the manual at the side or on your lap rather than have to switch screens to
look at the manual and back to look at your code.
--
Richard H. Miller                 Email: [e-mail]
Asst. Dir. for Technical Support  Voice: [phone]
Baylor College of Medicine        US Mail: One Baylor Plaza, 302H
                                           Houston, Texas 77030