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

[Simon Clubley]

On 2022-03-14, Bill Gunshannon <bill.gunshannon at gmail.com> wrote:
> On 3/14/22 09:58, Simon Clubley wrote:
>> 
>> Try to consider, as a VMS person, being asked to learn how to work with
>> z/OS and write software for it. An experienced z/OS person will not have
>> a problem because they are used to it. A newcomer to z/OS, OTOH, will see
>> all the strange new concepts and ways of doing things that they have never
>> encountered before and could easily be lost in a mass of detail.
>> 
>
> Not really.  I hadn't touched an IBM Mainframe since the DOS/E VM370
> days and had no problem doing the challenges on the Mastering the
> Mainframe program just a couple weeks ago.  The hardest parts had to
> do with stuff they use that runs on Linux.  All the z/OS stuff was a
> piece of cake.
>

Yes, but you clearly had prior experience and conceptual knowledge which
helped you. Many people these days simply don't have any prior knowledge
or even understanding of such things.

For example, consider that you have programmed in DEC Basic all your life
and then you have a C++ manual dumped in front of you and told that's what
you need to get up to speed on because that's what you will be using from
now on.

That's how different VMS would feel to someone who had only ever used Linux
and Windows and had absolutely no idea of the concepts behind VMS.

>> That feeling is exactly the same feeling that people new to VMS could
>> easily feel when they are exposed to an operating system with concepts
>> and ways of doing things they have never seen before.
>
> I still think learning VMS is harder.  I don't think it needs to be, but
> it is.
>

Do you have any specific examples why you think this is ?

Is it the lack of tutorial material ?

Overwhelming levels of detail in the documentation ?

Not enough reading guides about what trails to follow through the
documentation for various tasks ? (Or the fact that such trails don't
appear to exist for VMS ?)

For anyone interested, here's the trail for the Java Reflection functionality:

https://docs.oracle.com/javase/tutorial/reflect/index.html

It contains a mixture of tutorial/conceptual material along with links to
detailed reference material and includes code examples. That's the kind of
thing people expect these days and which is sorely lacking in the VMS
documentation set.

There's no point having a lot of documentation if you don't have task
orientated guides and tutorials to help you understand and navigate it.
That's how people get lost in a mass of detail.

Here's the main Java tutorial page:

https://docs.oracle.com/javase/tutorial/index.html

VMS badly needs task orientated guides like that as part of the
documentation set. Spending silly time wading through the documentation
set and gradually assembling clues to the pieces of knowledge you need
is not an acceptable approach these days.

The closest VMS comes are things like the programming concepts manuals
which jump in way too deeply way too quickly for any absolute newcomers
to VMS. None of us here would have any problems at all understanding the
material in those manuals if we wanted to learn a part of VMS that we
had not previously used, but we are not the kind of people that such
manuals should be written for these days.

At a minimum, there needs to be the kind of trail-based documentation
I have pointed to above as part of the VMS documentation set.

Simon.

-- 
Simon Clubley, clubley at remove_me.eisner.decus.org-Earth.UFP
Walking destinations on a map are further away than they appear.