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 www.adam-k-watts.com/clarity you will find a number of navigation links on the right-hand side. I hope they will be useful for you.

- Adam K. Watts

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.)

"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.

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.

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