I would really like to apply pressure to vendors like Microsoft to
support all three qualities specified by David.
When I discovered that the Windows Command line tools help moved
from a local help file to an internet based set of web pages, that
was really irritating. There are times when the computer on which I
am working is offline because of some troubleshooting measure, state
of intermediate configuration, or simply in a location that does not
have internet access. My idea of mastery is to understand and
remember *how* something works. Remembering every last detail of
command line options is not my idea of mastery, just my idea of
convenience. So, even though I may have 'mastered' some hardware or
software, I still want ready access to the documentation for the
product.
To be comprehensive and systematic the documentation should have a
table of contents and an index with a generous amount of cross
reference information. Part of the index could be full text
searching, but that usually is not comprehensive enough and does not
have sufficient cross reference information. You cannot apply full
text search to a video. If someone supplies captioning for the
video, there is something to index, but it won't be comprehensive
information about a product. To be local it must be accessible
without internet access.
-Stefan
On 3/12/2015 5:49 PM, David McFarlane
wrote:
[log in to unmask]"
type="cite">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