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

My IBM knowledge is mainly MVS 3.8 (obviously!) and some modern z/OS.
Even from the MVS 3.8 days, there's enough in there to give you a jump
start with getting up to speed with how modern z/OS works.

The hardware doesn't really matter in this case. It's the mindset and
general way of doing things that really matters.

In the DEC world, because of its origins, you can use RSX to help understand
some of the core VMS concepts. Hell, even some of the PDP-11 userland tools
are mostly the same regardless of which underlying PDP-11 operating system
they are running on.

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

Pascal's a little easier to learn than C++. :-)

>> 
>> 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 really. See below.

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

Neither did I when learning Java in general. However, I did use it
to learn how to use Reflection (which was an entirely new concept to me
for Java) and I found the material to be well written, pitched at just
the right level for an otherwise experienced programmer, and gave me
all the pointers I needed to jump into the reference manuals once
I understood how the concepts worked on Java.

It was massively better than trying to manually pull together the pieces
from the documentation and VMS could seriously do with material along
those lines as part of the documentation set.

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

And _that_ Bill is something that I agree with you about and why
I think a trail-based introduction to VMS-specific concepts would be
a really good thing.

I've just had another look at the programming concepts manual and while
_I_ have absolutely no problem understanding it, it does go way too deep
way too quickly for the absolute beginner and a newcomer could easily get
lost in the mass of fine detail. It's called a concepts manual, but that
manual was written for people like us. It wasn't written for absolute
newcomers to VMS.

Simon.

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