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