Discussion:
VMS documentation, was: Re: callable BACKUP example
Add Reply
Simon Clubley
2021-07-16 17:52:05 UTC
Reply
Permalink
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.

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.

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.

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

Simon.
--
Simon Clubley, ***@remove_me.eisner.decus.org-Earth.UFP
Walking destinations on a map are further away than they appear.
Stephen Hoffman
2021-07-16 20:33:21 UTC
Reply
Permalink
Post by Simon Clubley
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.
Post by Simon Clubley
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?".
Post by Simon Clubley
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.
Post by Simon Clubley
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
Arne Vajhøj
2021-07-16 23:28:32 UTC
Reply
Permalink
Post by Simon Clubley
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.
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.
Or switch entirely to web and HTML. Then making links to full
examples is easy.

Arne
Chris Townley
2021-07-16 23:53:11 UTC
Reply
Permalink
Post by Arne Vajhøj
Post by Simon Clubley
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.
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.
Or switch entirely to web and HTML. Then making links to full
examples is easy.
Arne
Not much use if they are hosted with HP/HPE - they kept changing them,
so any link was quickly useless.

ISTR IBM doing the same
--
Chris
Arne Vajhøj
2021-07-17 00:09:42 UTC
Reply
Permalink
Post by Chris Townley
Post by Arne Vajhøj
Post by Simon Clubley
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.
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.
Or switch entirely to web and HTML. Then making links to full
examples is easy.
Not much use if they are hosted with HP/HPE - they kept changing them,
so any link was quickly useless.
ISTR IBM doing the same
VMS is all VSI now. And they will have more focus on VMS.

But they should either allow download of full HTML doc set
so people can browser offline or ship the full HTML doc set
with VMS including a small web server for serving it or both.

Arne
Craig A. Berry
2021-07-17 01:14:01 UTC
Reply
Permalink
Post by Arne Vajhøj
Post by Simon Clubley
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.
Or switch entirely to web and HTML. Then making links to full
examples is easy.
HTML would be a poor source format for anything as large and complex as
the VMS doc set. At some point they were talking about XML in the
DocBook schema and that would make sense. Then the docs could be easily
transformed into HTML, PDF, ePub, MarkDown, or whatever. Embedding
and/or providing links to examples shouldn't pose any problem.

Loading...