Blog Tools
Edit your Blog
Build a Blog
View Profile
« July 2024 »
1 2 3 4 5 6
7 8 9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
28 29 30 31
You are not logged in. Log in
Entries by Topic
All topics  «
Site Info
Technical Writing
Writing Portfolio
XML Article on XML
Photography/Graphics Portfolio
My Photography
Blog - Various Musings
Tuesday, 3 November 2009
This Website
Topic: Site Info

My website, to which this blog is attached, was developed for a number of reasons. Not the least of which is to serve as a demonstration of my web design. "Clarity Communications" is not a real company. However, the services listed are very real.

Another reason for the site is to provide an easy place to display my portfolio of work.

The site originally began for personal, rather than professional reasons. This original purpose is still reflected in the site contents. I have a number of pages containing links and information for a number of topics. Of course, you can perform your own search and locate resources yourself. My resource pages are simply an add-free collection of relavent websites and pages. From the main page of you will find a number of navigation links on the right-hand side. I hope they will be useful for you.

- Adam K. Watts

Posted by adam-k-watts at 11:08 AM PST
Updated: Thursday, 26 March 2015 12:24 PM PDT
Log in to Comment | Permalink
A Brief Note On Technical Writing
Topic: Technical Writing
User Documentation

There is no debate over the fact that easily accessible, thorough and comprehensible system documentation makes life easier for the end-user, while relieving pressure on technical support staff (and the corporate support budget.)

Why Use a Technical Writer?

"Writing" is something that anyone who can form letters and rudimentary sentences can do. However, communicating thoroughly and effectively to a given audience is another matter entirely.

It is a common misconception that developers and engineers should be utilized for end-user documentation because "they know the system so well." Although rare exceptions do exist, this is normally a bad idea for a number of reasons:

  • Developers and engineers know the system too well. Consequently it does not occur to them to explain details, which they may take for granted, that may be completely new to the end-user or even to the technician. The expression "this reads like stereo instructions" originates from this type of situation. 
  • The level of in-depth familiarity and understanding of the system will also tend to adversely affect their descriptions, often lending a proclivity to include programmatic process information or references that are completely confusing and irrelevant to the end-user.
  • Developers and engineers are highly technical people, normally with extensive training and/or experience. This provides them a large vocabulary of technical jargon that makes communicating with each other very simple, while presenting a string of incomprehensible gibberish to the layperson.

When tightening the corporate belt, executives often consider it cost effective to have system developers create the end-user documentation for the systems they are creating. This enables them to pay fewer employees. However, documentation development time does not significantly change. The result is that the (usually) higher paid developers must invest this time to perform a function that they are normally untrained and unsuited for, to produce documentation that is most commonly far inferior to that which would be produced by a technical writer.

Enter the Technical Writer:

A technical writer is a comprehension specialist; a translator between the developer and the end user. To be effective, a technical writer must be proficient in both technical and non-technical terminology. A technical writer must be tech savvy enough to dive into a system he has never seen before and come out the other side with a complete manual.

The technical writer maps the ins and outs of the system from the user perspective, the technician perspective, or the management perspective, depending on the type of document being created, and creates a clear, concise and relevant document for the intended audience.

What About Combining Technical Writing and Programming Positions?

This is not usually a good idea. If the potential employee has good programming skills, he would not be seeking work at the lower rates of a technical writer. The result is that you get someone that CAN program, but probably not as well (or as mistake free) as you would wish. The better the programmer, the more you will encounter the problems listed above.

The best solution is: Do not try to cut corners, put the right person on the right job the first time.

- Adam K. Watts

Posted by adam-k-watts at 10:56 AM PST
Updated: Tuesday, 3 November 2009 11:39 AM PST
Log in to Comment | Permalink

Newer | Latest | Older