peter@sugar.hackercorp.com (Peter da Silva) (06/17/91)
Warning: rampant anti-DEC flame. Respect followups. In article <VINSCI.91Jun14003452@nic.nic.funet.fi> vinsci@nic.funet.fi (Leonard Norrgard) writes: > Add VMS from Digital to the list. Now the difference with their source > code is that it is clean and readable. That would be a nice change from their documentation, AKA the "Orange Wall". Oh, individual sections are well written, use proper english, are very clear, and so on... but there's no usable cross-reference, no reference section worth the name (they seem to think people should be able to use a tutorial as a reference manual), and so on. Every time I want to do something on the damned VAXes it's hell finding out what I need. Even something as simple as a terminal server comes with 3 volumes! > Something I've not yet heard about CBM's (cf. the code in the RKM's). On the other hand, the RKMs themselves are excellent *reference* manuals. There is a lack of decent tutorial material and working examples, but you can find out what a given function does, how it should be called, and so on without having to spend hours digging stuff up. > Of course, here another difference comes > up, in that VMS is actually *documented*. Nice, very clean > descriptions of each OS/library function, This must be in some extra manual not shipped in the standard orange wall, right? > and that documentation was written by *technical writers*, Technical writers are great, but they should spend some time with the people who actually want to use the manuals instead of blindly following their design rules. -- Peter da Silva. `-_-' <peter@sugar.neosoft.com>. 'U` "Have you hugged your wolf today?"
vinsci@nic.funet.fi (Leonard Norrgard) (06/18/91)
In article <1991Jun17.142942.2952@sugar.hackercorp.com> peter@sugar.hackercorp.com (Peter da Silva) writes: Warning: rampant anti-DEC flame. Respect followups. Fair warning. :-) In article <VINSCI.91Jun14003452@nic.nic.funet.fi> vinsci@nic.funet.fi (Leonard Norrgard) writes: > Add VMS from Digital to the list. Now the difference with their source > code is that it is clean and readable. That would be a nice change from their documentation, AKA the "Orange Wall". Oh, individual sections are well written, use proper english, are very clear, and so on... but there's no usable cross-reference, no reference section worth the name (they seem to think people should be able to use a tutorial as a reference manual), and so on. Every time I want to do something on the damned VAXes it's hell finding out what I need. Even something as simple as a terminal server comes with 3 volumes! And compared to Amiga documentation this is ...? Sure, it is not perfect, but the Amiga documentation is inferior in every way I can think of (of course, I don't think about documentation for a living). > Something I've not yet heard about CBM's (cf. the code in the RKM's). On the other hand, the RKMs themselves are excellent *reference* manuals. There is a lack of decent tutorial material and working examples, but you can find out what a given function does, how it should be called, and so on without having to spend hours digging stuff up. I beg to differ with the RKM reference manuals part. You'd better know all of the stuff by heart before trying to find out where something is documented. When you finally find (hopefully) a section on it, you'll note that you have some guesswork to do, because the person writing that section wasn't in your situation, but rather knew everything already and so didn't write down all things this depended on (like why doesn't amiga autodocs specify what files you must *include* for FooBar() to work?). The RKM example source also tends to not follow the CBM guidelines for practically anything, starting with testing return values from library calls *and handling them in the appropriate way*. Another problem with the RKM's seems to be that they're constantly outdated by a year or so. > Of course, here another difference comes > up, in that VMS is actually *documented*. Nice, very clean > descriptions of each OS/library function, This must be in some extra manual not shipped in the standard orange wall, right? You've appearantly read a different set of manuals, or you are not giving due credits. Amiga autodocs simply doesn't compete in the same league. > and that documentation was written by *technical writers*, Technical writers are great, but they should spend some time with the people who actually want to use the manuals instead of blindly following their design rules. Sorry, I have no info on their social habits. :-) Peter da Silva. `-_-' <peter@sugar.neosoft.com>. -- Leonard
thad@public.BTR.COM (Thaddeus P. Floryan) (06/18/91)
There's simply NO argument: DEC documentation sucks dead bunnies thru a straw.
Just even try to find ONE example (in the Sys.Services, C Lang Ref, etc.) that
will work if entered as printed (re: VMS (the DEC-10 and DEC-20 stuff was OK)).
But that's DEC's problem.
As for the Amiga's documentation, I haven't had occasion to be overly critical
since I was able to test EVERY function using the published docs as early as
mid-1985.
And what makes it even easier (NOW) is the series of books published by David
Lai: The Amiga Developer's Reference Guide(s).
If you are familiar with and feel at-home with UNIX-style permuted indices and
completed cross-references of all structures, members, lib functions, etc.
then you'll like this series of books. His first volume covered 1.1, then
the volumes for 1.2 and 1.3 appeared coincident with their releases.
From the 1.3 Edition (which I got back in January 1989):
-- Include files analyzed
-- All functions prototyped, and completely cross-referenced
-- All symbols cross-referenced
-- Perfect companion to the Amiga RKM; a real time-saver
Now, I haven't seen the guy in over two years (at a BADGE or FAUG meeting);
last I heard he was up in Canada at McGill Univ.. These volumes were/are
available at the (local) Amiga dealer in Silicon Valley (HT Electronics, Inc.;
Sunnyvale CA) and from the publisher per:
AMIGA Developers Reference Guide
ISBN 0-945119-02-X
Pacific Press
P.O. Box 611075
San Jose, CA 95161-1075
List price (for "Edition 1.3") is/was US$19.95
Dunno if he has an "Edition 2.0" in the works.
Thad Floryan [ thad@btr.com (OR) {decwrl, mips, fernwood}!btr!thad ]plouff@kali.enet.dec.com (Wes Plouff) (06/19/91)
In article <1991Jun17.142942.2952@sugar.hackercorp.com>, peter@sugar.hackercorp.com (Peter da Silva) writes... >Warning: rampant anti-DEC flame. Respect followups. > >That would be a nice change from their documentation, AKA the "Orange Wall". Out of date. Now gray. >Oh, individual sections are well written, use proper english, are very clear, >and so on... but there's no usable cross-reference, no reference section >worth the name (they seem to think people should be able to use a tutorial >as a reference manual), and so on. The _VMS General User's Manual_, order number AA-LA98A-TE, contains both tutorial and reference sections, much like the old blue Osborne 1 manual. >Every time I want to do something on the >damned VAXes it's hell finding out what I need. Even something as simple as >a terminal server comes with 3 volumes! Not since April. (hee, hee!) Read the newspapers... Please note my affiliation. Also, no slight intended to Peter Da Silva. This posting is just to inject a few facts into the discussion. -- Wes Plouff, Digital Equipment Corp, Maynard, Mass. plouff@kali.enet.dec.com Networking bibliography: _Islands in the Net_, by Bruce Sterling _The Matrix_, by John S. Quarterman
peter@sugar.hackercorp.com (Peter da Silva) (06/19/91)
In article <VINSCI.91Jun18044538@nic.nic.funet.fi> vinsci@nic.funet.fi (Leonard Norrgard) writes: > I beg to differ with the RKM reference manuals part. You'd better know > all of the stuff by heart before trying to find out where something is > documented. I don't agree. They're not tutorials: you have to be pretty familiar with the Amiga to use them effectively, but when you do they're *way* better than what DEC provides. Get other sources for tutorials, fine. But I haven't seen better references than the RKM. > Another problem with the RKM's seems to be that they're constantly > outdated by a year or so. That's a perennial problem with *all* paper manuals. -- Peter da Silva. `-_-' <peter@sugar.neosoft.com>. 'U` "Have you hugged your wolf today?"