Weekend Scripter: The Changing Nature of Documentation

Doctor Scripto

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 


Discussion is closed.

Feedback usabilla icon