From: ross@cbmvax.commodore.com (Ross Hippely - Manuals)
Newsgroups: comp.sys.amiga.misc
Subject: Re: Commodity question
Summary: Docs are stupid things...
Keywords: documentation manual enforcer 2.04
Date: 8 Jan 93 16:08:51 GMT
Reply-To: ross@cbmvax.commodore.com (Ross Hippely - Manuals)
Followup-To: comp.sys.amiga.misc
Organization: Commodore, West Chester, PA

In article <wanderer.03pd@tcsi.appleton.mil.wi.us> wanderer@tcsi.appleton.mil.wi.us (K.T. Wieringa) writes:
>Ross Hippely - Manuals (ross@cbmvax.commodore.com) wrote:
>: In article <wanderer.03nq@tcsi.appleton.mil.wi.us> wanderer@tcsi.appleton.mil.wi.us (K.T. Wieringa) writes:

>Another person mailed me saying that enforcer wasn't part of the OS
>distribution.  It seems to have come with mine; both on the hard drive
>(sys:tools) and on the install3000 disk.  I was wondering if there was 
>any documentation included.  I haven't found any.
>
>: >Still haven't found it in the big book 
>: 
>: And could you refresh my memory on where in _Using the System Software_ 
>: (not a new manual, by the way) Enforcer is mentioned?  
>
>I think that was my point.  It's part of the OS disk distribution, but the
>documentation isn't?

Right.  My point was to establish whether there was any place in the docs
that told you to use Enforcer.  As a rule, if it's not mentioned in the
docs, you are not expected to mess with it.  (Or rather, you're *expected*
to mess with it, but only at your own risk ;-)

There are lots of things that appear on disks that we give you--especially
Install disks--that are necessary for some reason, but which are there to
be used by another piece of software, or under certain special conditions,
and which can and should be ignored by users.  I understand the temptation
to try out the mystery files, and the desire to have everything documented.
But believe me, if we really documented *everything* _Using the System
Software_ would have needed *two* binders.

Now I won't claim that we do in fact always succeed in documenting everything
you do need to know, but we try.  "If you don't know what it is, leave it
alone" remains a fairly good rule to live by.  Even for Amiga folks ;-)

> As far as detailed constructive criticism goes,
>
> -  I'd find it real helpful if there was some kind of appendix or 
>    supplement available which covered, or at least cross referenced, 
>    upgrading from one OS to another.  Something for those of us who know
>    the basics but would like to more easily parse the differences without
>    having to wade through the simple stuff all over again.

If you upgraded to 2.0, you should have received the _Getting Started_
manual, which does just that.  If you bought a system with 2.0 already on
it, you wouldn't get this, but it would be much less necessary.

> -  The Index could use some work (in my opinion). [...]

I wouldn't argue with you there.  The most pertinent comment I can make is
that for _UtSS_ (everything pre-2.1, actually), the index was done be hand.
We now have partially automated indexing, which is much easier, hence much
less likely to leave out important references.

> -  some of the requestors in the diagrams differ quite a bit in available
>    options from the ones on my screen (prefs/screenmode and prefs/overscan
>    are two that come to mind).

An inevitable consequence of manual development in parallel with software
development.  I think we put a disclaimer up front that said "screens
may differ from the illustrations" or something, in an attempt to cover
ourselves. :-)

> -  how often do you really send out upgrades for this manual?  [...]

We don't really send out upgrades.  But there were one or two "change
pages" inserts we created to throw in the box with the older manuals
when there were significant changes.

> [...] is the looseleaf format really 
> necessary?  It doesn't seem near as durable as a bound manual.  [...]

In some ways it is, in others it isn't.  People seem to be split on whether
they like the binder.  We have gone to all perfect binding for large manuals
now, for cost reasons.

>And we can be such picky SOB's  :-). 

No offense taken.

>I try to avoid judging on the basis of things that aren't yet available.

Good point!  At least the people buying current systems can get examples
of improved manuals.

[...]
> | K.T. Wieringa              UUCP: toddw@tcsi.appleton.mil.wi.us |
> | Shawano, Wisconsin, USA    Fido: K.T. Wieringa @ 1:238/105.3   |

-- 
----------------------------------------------------------------------------
Ross Hippely:                                               Technical Writer
employed by, not speaking for:              Commodore Business Machines Inc.