Quality requirements for technical documentation are lower than user documentation

Ok, don’t freak out now …

All I want to point out is that the apparent need for screen prints of every step in the process is a bit overdone, especially when we’re talking about technical documents.

Screen prints / images in the documentation typically means the electronic documents get unmanageably huge, even if you shrink the .JPGs, and few people know how to do that. Plus, you indirectly commit yourself / your organization to a huge maintenance burden. because if/when the screen is even slightly different than what is on the printed page, your audience will get confused, and the support calls will come in.

Remember, your audience is technical, and shouldn’t need to be led thru every teeny tiny step. You can make assumptions that they understand some things. So follow the Microsoft help method, and describe things by naming dialogs and tabs, & laying out menu paths.

Here is a sample from a Web Site administrator’s guide. It’s a tad dated, I believe it’s Win2K server, but your get the idea …

  1. Create the site using the IIS Management Console; select Action, New, Site, and use the Web Site Creation Wizard(click Next to start):
    • Enter a description – for development sites, usually we use the URL and add “(Development)” to the end (click Next).
    • IP Address; usually the same as other sites, for the most part we use host headers to do our internal development (click Next).
    • Specify the directory created in step 5 for the home directory. Leave the Allow Anonymous Access box checked. (click Next).
    • Click Next to take the defaults on the permissions page, and exit the Wizard.
  2. While still in the IIS MMC, select the node for the site you just created. Right click, and select Properties – we need to make a few adjustments …
    • On the HTTP Headers tab, check Enable Content Expiration, and select Expire Immediately. This is preferred for development sites, where content can change quickly.

This Post Has 0 Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

Related Articles

IoT Field Notes: Solving Interesting Tech Challenges 2

Three more types of tech challenges that come up in conversations about Smart, Connected Products. The details are interesting, but the higher-level insights are very informative.

Read more

IoT Field Notes: Solving Interesting Tech Challenges

Another practical story of tech discovery, as we labor to solve the Communication problem for one of a class of devices / products.

Read more

More Thoughts on Why Techs Don’t Like Documentation

A few years ago, I was interviewing candidates for a systems analyst job, and trotted out one of my standard…

Read more