[Info-vax] VMS documentation, was: Re: callable BACKUP example

[Stephen Hoffman]

On 2021-07-16 17:52:05 +0000, Simon Clubley said:

> On 2021-07-15, Arne Vajhøj <arne at vajhoej.dk> wrote:
>> 
>> A complete example makes it easy to copy paste and show some of the 
>> extra stuff that need to be done in final code.
>> 
>> But a complete example also tend to be much bigger and taking much more 
>> time to read than a snippet that only show the the specific stuff the 
>> example need to illustrate.
>> 
> 
> Each VMS .pdf manual that contains extracts from source code examples 
> should also come with a .zip file at the same location as the .pdf 
> manual which contains the full versions of those examples. A .zip 
> archive is preferable to placing the code in sys$examples: because it 
> keeps the manual and the source code together.

I'm used to example integration within the analogs of HELP. (This gets 
back to why the HELP tooling needs, well, help.)

What I'm used to? Click a link in the doc viewer, and get a buildable 
example of the API downloaded into your preferred download directory.

With this, the need for in-line example code—past a one-line template 
or so—largely disappears.

> Use extracts from the full examples to explain certain points within 
> the manuals and then provide the full source code for those examples 
> somewhere outside of the .pdf.

I'd transition to and use the examples as the documentation, at that 
level of detail.

This ties back to the ill-suited nature of the existing HELP tooling on 
OpenVMS, and the use of source code in PDFs.

Within DEC-era documentation, the source code examples are treated as a 
second- or third-class or steerage-level resource, rather than a 
fundamental part of programming documentation.

Also tied into this whole area is marketing; of explaining the 
value-added products and services available from VSI and partners. Of 
why you might want to use this new feature or new API, because it's not 
always obvious. Of answering "why?".

> The licences should also permit unrestricted use and distribution of 
> that source code. Look at the EVE source code in sys$examples: for an 
> example of a licence that you do _NOT_ want to see on that source code.

Ayup.

> BTW, talking about manuals, am I the only one to find the new manual 
> layouts less readable than the old VAX Document style layouts ?

Documentation is tougher than it looks, and good tech writers scarce 
and valuable, and navigation and contents have all moved on from the 
DEC-era norms.

-- 
Pure Personal Opinion | HoffmanLabs LLC