[Info-vax] OpenVMS STARTUP Whitepaper

[Stephen Hoffman]

On 2020-12-03 18:09:25 +0000, geze... at rlgsc.com said:

> The OpenVMS STARTUP process is documented, but the information is 
> spread across several different manuals and files...

Welcome to OpenVMS, where the doc is commonly and unfortunately quite 
scattershot and in need of an overhaul, and where the cookbook-style 
presentation is lacking.

Section 11 is missing the "why" for the items listed. That detail might 
be obvious to the writer, but not to the reader. Some New Features 
documentation is notorious for this—here's this feature, but omitting 
why you might want to adopt it.

Not much on SYSMAN in that whitepaper, that being an approach you've 
oft preferred per our previous discussions, and an approach I've become 
fond of when seeking to "hide" startups.

And as for the previous discussions here, this document seems thin in 
the relevant section for that discussion; section 11. What can be fixed 
or updated, what's missing. Better app packaging and app isolation and 
automated means to add and remove app startups has been an ongoing 
mess. Most apps scatter at least part of themselves into various spots 
on an OpenVMS boot device, often requiring manual steps by the system 
manager / app developer / app support team / Jada, the person on staff 
that keeps that old server going. And the creation of documentation for 
the end-user, since this presently can't be reliably automated within 
OpenVMS.

As I've commented previously from the earlier thread, hand-editing a 
file to add a startup is archaic and error-prone and somewhere between 
silly and stupid, but that's on OpenVMS and not on you. And manually 
invoking SYSMAN to add a startup isn't appreciably better, and that 
approach is documented and used used in approximately no layered 
products. And manually removing those same entries, if/when necessary. 
And whatever else the installer added. PCSI tries, but there are holes 
there.

And as for cookbook documentation more generally, background and 
internals are prolly best left in an appendix at most (e.g. first 10 
sections, here), with a discussion of options and alternatives for 
developers as the focus. How an end-user or a layered product might use 
the startups, and what options and alternatives exist. Because I'd 
really rather not have to know how the OpenVMS startups work, outside 
of the minimum necessary for an app developer or installation kit 
author or suchlike to add and to remove the app and the startup.

And as for passive voice in technical documentation, I prefer to avoid 
passive voice in cases where active voice fits. Which is usually. 
Passive voice is best left for assuaging for or deflecting after some 
screw-up, for cover-ups and related backside-covering, or variously as 
part of any efforts toward avoiding having or avoiding stating an 
opinion. Put differently, encountering passive voice can be inferred to 
indicate you're dealing with somebody trying to hide something. One can 
of course have other opinions for oneself, as one often does.


-- 
Pure Personal Opinion | HoffmanLabs LLC