Path: utzoo!utgpu!news-server.csri.toronto.edu!bonnie.concordia.ca!uunet!mcsun!news.funet.fi!funic!nic!vinsci From: vinsci@nic.funet.fi (Leonard Norrgard) Newsgroups: comp.sys.amiga.advocacy Subject: Re: DEC Documentation? Hahaahahahahahahhhhaaaaaaaa Message-ID: Date: 18 Jun 91 02:45:38 GMT References: <3036@public.BTR.COM> <1991Jun17.142942.2952@sugar.hackercorp.com> Sender: vinsci@nic.funet.fi (Leonard Norrgard) Followup-To: comp.sys.amiga.advocacy Organization: Soft Service, Inc. Lines: 64 In-Reply-To: peter@sugar.hackercorp.com's message of 17 Jun 91 14:29:42 GMT 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@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. `-_-' . -- Leonard