I agree, to an extent, that online documentation is extremely poor in some cases. Some vendors do it well (as an example, I quite like the PaperCut online documentation, which is well indexed, searchable and all .HTML so I can easily farm and capture it to my laptop!) Video "how to" examples are a great supplement to documentation, but a poor substitute for it. I much prefer getting documentation as well indexed PDF format as opposed to printed material, as I can load up a tablet with documentation. Carrying 20+ .PDF manuals in a tablet beats filling two overhead bins with printed books, at least for the way I work.
I recently looked at a vendor offering a "freemium" service, where the software was free, but you needed to pay a small fee per license for updates and support calls. When I asked them for documentation, the sent me what was obviously a marketing PowerPoint (in landscape format), to which they had added a dozen or so slides with technical content, then converted it to a .PDF for easy reading. Obviously, I didn't go with their product.
John Resotko
Assistant Director, Systems Administration and Support
Michigan State University College of Law
email: [log in to unmask]
phone: 517-432-6836
-----Original Message-----
From: David McFarlane [mailto:[log in to unmask]]
Sent: Thursday, March 12, 2015 5:49 PM
To: [log in to unmask]
Subject: [MSUNAG] RANT: Why I still demand traditional "printable" manuals
My apologies for polluting your inboxes with my personal rant, but here goes ...
I demand documentation that has the following
qualities: Comprehensive, Systematic, Local (which brings along the
quality of Durable or Lasting), and Personalized Pacing.
Lately, every time I ask for "documentation", people blithely steer
me to some websites, and often specifically to videos. These in
particular fail on every count:
- Video collections are selective. Even if I diligently view all the
videos (which would take too much of my time), they will not expose
me to *every* aspect of the system, unlike traditional
documentation. I.e., video collections fail to cover matters comprehensively.
- Video collections do not provide a clear orderly path for viewing
the entire collection, unlike traditional documentation with a fixed,
known sequence of pages to follow. Websites are totally hopeless in
this regard. And forget about leaving bookmarks so that I can pause
and later pick up where I left off. So video collections fail at
systematicity.
- Streaming video collections require online connectivity at every
moment. I cannot view streaming videos, or a website, while offline,
unlike traditional documentation. This also makes them ephemeral,
bound to disappear at the whim or fortunes of the provider; by
contrast, traditional documentation lives with me, and lasts as long
as I hold onto it. So video collections fail to be "local", and with
that fail to be durable or lasting.
- Video collections force me to proceed exactly at the pace of the
video. Unlike traditional documentation, I cannot "skim" videos to
get the gist of the content, and then come back to drill down to
details of interest. So video collections fail the test of
personalized pacing.
Much of this critique applies to other forms of modern
"documentation", e.g., websites and downloadable html collections in
particular. A good .pdf, or set of .pdfs, however, may have these
qualities, just as a traditional set of printed manuals did back in
the day. Given a traditional manual set of, say, 1000 pages, I can
master any system in a matter of days. Doing things the modern way
puts me at the mercy of a chaotic collection of people of dubious
mastery, and impedes my own attainment of mastery.
OK, now you kids get off my lawn!
-- dkm
|
