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

[Bill Gunshannon]

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

MVS was outside my experience.  I did DOS/E which was a modified version
of DOS for DOD.  Ran on those trailer mounted 360/40.

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

My mindset is not to any particular OS or vendor.  I have worked at the
application and systems level on at least a dozen different systems.

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

My RSX experience is very limited. First used it as a beltway bandit and
didn't really like it.

> 
>>>
>>> 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++. :-)

The much more experienced programmers where I was working at the time
would not agree with you.  That's why I got the task.

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

The only books I have seen that I would say were written for the rank
beginner were "VMS for Unix Users" and Unix for VMS Users" (or some
very similar titles) and the couple of VAX-11 BASIC books I still have.

:-)

bill