Weekend Scripter: The Changing Nature of Documentation

Summary: Microsoft Scripting Guy, Ed Wilson, talks about the changing nature of documentation.

Microsoft Scripting Guy, Ed Wilson, is here. This week, we announced Microsoft HoloLens during the Windows 10: The Next Chapter webcast. I mean, I want one—badly.

This is going to be an incredible year. The excitement of holographic computing has me thinking about Star Trek. Of course last year, we introduced a holodeck—so the future is now, so to speak.

But then I was thinking, "Does one ship a stack of books along with the HoloLens?" It doesn’t make sense, I suppose. Back when we shipped Windows NT 3.51, there were books and books and books of documentation for the product. I mean, stacks of disks and stacks of books. Here is a picture I had our archives people dig up:

Image of books

In fact, when I bought my first computer (an Osborn 1), it came with lots of books. My most recent laptop purchase, however, did not come with anything but a stack of legal disclaimers. My toothbrush came with more documentation. (Actually, I was wondering about toothbrush documentation, and I did a quick Bing search. 7,500,000 pages returned, including YouTube videos and pages of documentation from the Centers for Disease Control and Prevention.)

Anyway, I did not bother to read all that stuff, and usability studies found that most people did not bother to read it either.

When I get ready to install and configure a new software application, I do not want to read through a bunch of marketing stuff telling me how great the software is. Dude, I already bought it. What I want is a quick start guide that tells me exactly what I need to do to quickly get the thing up and running. But that is just me. Other people prefer (in fact, they need) a features guide to tell them what features are available. Others need marketing material so they can help sell the application to their management. Still other people are visual learners, and they need a picture, a diagram, or a video that shows them exactly how to configure the application.

As far as I am concerned, images are great. I also like samples of working code. I still have nightmares about some documentation that says: To print, click the Print button from the Print menu. But when I look at the application, I cannot find the Print menu. I mean clicking the Print button would be an obvious choice, but where is the silly thing hidden? And the documentation didn’t tell me.

Many times, I want to hear real advice from people who use the product for a living. This is why I love blogs so much. In the Windows PowerShell world, most of the MVPs maintain blogs, or they contribute to blogs.

In the old days, documentation was pretty much a book that came as a big box of disks. Today, documentation is much more customized, and it comes in many forms. In fact, documentation comes in the form of wiki articles, blog posts, videos, webcasts, discussion forums, and various forms of social media. The cool thing is that I can find exactly what I need pretty much when I need it. All I need is access to a search engine and the Internet—which is pretty much all of the time.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy 

Comments (5)

  1. I am going to print this for my archive 🙂

  2. jrv says:

    The Internet was born when Berners-Lee decided to use hypertext to improve the ability to document physics information. What we see now is the current stage of this evolutionary process. The presentation and usability is getting much better and exceeds
    that of paper print mediums. The electronic readers are also becoming more useable.

    I still love to sit down with a good book. Paper books are the ultimate in portability for recreational purposes. You can even read them on a sun drenched beach in all of that sand, wind and salt water and the batteries never need to be recharged.

  3. Raj Chaudhuri says:

    In the days of yore, software typically came with a User Guide which introduced the concept of the software to you, and one or more Reference Guides which gave detail about specific features. In PowerShell terms, the User Guide was "Get-Help about_*" (only
    better organized), whereas the Reference Guide was "Get-Command | Get-Help" (ditto).

    I’m one of those people who used to read the User Guide from page to page, and then use the Reference Guide for…well, reference. I didn’t complain when the Reference Guide got replaced with .HLP and then .CHM files and finally MSDN Library online, but really,
    really miss mourn the demise of the User Guide.

    I really, really hate the documentation via social media (wiki, blog, webcasts, forums) trend. There is a lot less attention to detail about accuracy, and while having the whole internet check and correct you seems like an advantage, it also means that I have
    to read the entire "trail" to get full and accurate information. To say nothing of the total lack of structure.

    Using an internet search engine to locate information can be dangerous, as people may end up finding the "loudest" information rather than the most correct. Also, how does one search videos or podcasts?

    I would love to see the day when the first place anyone looks for help about software is first-party documentation that is included with the product. Printed would be nice for this bibliophile, but .CHM will do. Powershell, incidentally, is doing a very good
    job in this regard.

  4. Fabien Dibot says:

    I do like books, and i still buy lots of them when i want to learn a new technology, nothing replace a good old book and a lab 🙂

  5. imfrancisd says:

    How many people who don’t read the documentation actually know how to use the product?

    I once knew someone who bought one of those pull-up bars that gets attached to the door. One day, he told me that the bar fell off when he was doing pull-ups, hurt himself, and was really angry at the company.

    I asked him if he attached the little clip on the pull-up bar.

    He asked, "What little clip?".

    I told him, "The little clip that came with the bar. It says in the directions to attach it, and not to do pull-ups so fast that the bar slips off the door."

    He responded with something like, "No one reads the directions." And he ended up hurting himself.

    The thing I like about good documentation (real documentation, not just the few sentences that comes up in intellisense) is that reading it for a few minutes will save me hours or even days of search and trial and error. And, I’ll actually know how to use the
    product, not just think I do.

Skip to main content