Your feedback is appreciated ...

Development

Quality requirements for technical documentation are lower than user documentation

Science, with some elements of Execution

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.

Discussion

No comments for “Quality requirements for technical documentation are lower than user documentation”

Post a comment

*
http://www.cazh1.com/quality-requirements-for-technical-documentation-are-lower-than-user-documentation/
www.cazh1.com
crawl=CC-MAIN-2015-18
50423
application/http; msgtype=response
sha1:UBUIKHXFMUUKQKAWYEM4UYZCLBFZRIHH
<urn:uuid:cca908dd-b554-462d-8938-e67adb1ab1e3>
2015-04-19T08:55:14Z
74.208.28.205
sha1:AQF3CGUUHEG2T2G4RT2YE4EZARYKKSEK
<urn:uuid:350fdcea-f60e-47c9-9a89-fc323e3d260d>
http://www.cazh1.com/quality-requirements-for-technical-documentation-are-lower-than-user-documentation/
length
response
<urn:uuid:40e2d355-0dc6-43c3-b4e0-360ca7f3ae81>
robots: classic
hostname: ip-10-235-10-82.ec2.internal
software: Nutch 1.6 (CC)/CC WarcExport 1.0
isPartOf: CC-MAIN-2015-18
operator: CommonCrawl Admin
description: Wide crawl of the web for April 2015
publisher: CommonCrawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf