[Info-vax] VMS documentation, was: Re: Special deals on Tape Drives

[abrsvc]

On Saturday, March 12, 2022 at 1:53:08 PM UTC-5, Simon Clubley wrote:
> On 2022-03-12, Scott Dorsey <klu... at panix.com> wrote: 
> > Simon Clubley <clubley at remove_me.eisner.decus.org-Earth.UFP> wrote: 
> >>On 2022-03-08, Dave Froble <da... at tsoft-inc.com> wrote: 
> >>> 
> >>> So, you were born with this knowledge about Linux? 
> >>> 
> >>> I do so dislike double standards ... 
> >> 
> >>Huh ???? 
> >> 
> >>_WHAT_ double standards ? 
> > 
> > I think his argument is that you had to learn both Linux and VMS operations 
> > somewhere. 
> > 
> 
> Like I said Scott, _what_ double standards ? 
> 
> At no point have I claimed to have learnt something without reading 
> the documentation and Bill's argument seems to be that he found the 
> VMS documentation more difficult to read than the Unix documentation 
> he has used. 
> 
> I don't know what Bill found to be confusing, but I can see some people 
> being confused by all the VMS-specific stuff such as a way over-complex 
> descriptor system, as well as the fact the documentation needs to be 
> written at a lower level than with the Unix documentation to deal with 
> all the exposed structures that in Unix are hidden behind call interfaces, 
> C structs, etc. 
> 
> There's a strong argument for using a clean and simple descriptor setup 
> instead of null terminated strings. Unfortunately, the VMS descriptor 
> setup is neither clean or simple. 
> 
> I can also only imagine what a newcomer to VMS would think if you have 
> to get them up to speed on the combined 32-bit/64-bit program executables 
> and how that compares to how cleaner what they are used to is. 
> 
> > And I don't know about you, but I find the Gray Wall and associated tutorial 
> > manuals to be a lot better-written and more useful than the Linux man pages. 
> > 
> 
> I see the man pages as a mixture of reference material and online help 
> (and vastly better than the VMS help, which is written for a ASR-33 user 
> input device, is chopped up into little pieces, has no built-in search 
> capability, etc). 
> 
> There are also full searchable reference manuals for all the GNU components 
> (and some other components) shipped as part of Linux. 
> 
> I can also find full public documentation for Linux for the things I am 
> not allowed to know about in VMS or cannot implement easily (such as how 
> to add a new filesystem to VMS or how to write a new CLI). 
> 
> Simon. 
> 
> -- 
> Simon Clubley, clubley at remove_me.eisner.decus.org-Earth.UFP 
> Walking destinations on a map are further away than they appear.

It seems to me that we need to differentiate between the documentation being difficult or the information documented being difficult.  From your own posting you state that descriptors are difficult.  OK (not to me but...) if that TOPIC is difficult, it has nothing to do with the documentation unless the explanation needs further edits to make it more clear.  If the topic is difficult to understand, take a class and ask questions from someone that can provide other examples or walk you through it.  Stating that the Linux/Unix stuff is better because it is hifdden behind easier interfaces, avoids the problem not solve it.