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

[Bill Gunshannon]

On 3/14/22 15:30, Simon Clubley wrote:
> 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.

Do you really think there is any similarity between DOS/E on a 4331
running VM/370 40 years ago and a current zSystem run z/OS?  You really
have no knowledge of Big Blue, do you?

> 
> 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.

Been there, done that.  Took the Jensen and Wirth "Users Manual and
Report" with me on vacation and learned Pascal in two weeks.

> 
> 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 ?

I just find the explanations to be poor.  I find it very difficult
to find things I need in the documentation.  But that could just
be me.  :-)

> 
> 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

There are enough third party books on Java it is unlikely I would
ever look at any of that.  And I didn't when learning Java,

> 
> 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.

If I had to state an opinion, it would be that the documentation seems
to me to assume to much pre-knowledge on the part of the reader.  It
assumes one is already an experienced professional with experience using
VMS and therefore no clarifications are necessary.  But, again, that
could be just me.

bill