Technical Writing Resources

Sunday, January 23, 2005

Being a Technical Writer

What's the difference between a technical writer and a technical writer? Depends on who you ask, but it can often be measured in tens of thousands of dollars annually, dramatically reduced frustration in working with developers and engineers, freedom to work more independently, effectively, and efficiently than you thought possible, and even in the ability to telecommute or freelance more readily.

Truly being--or becoming--a techie writer requires that your perspective shift from being a consumer of information (provided by developers or other experts) to being both a consumer and a co-developer. While you may very well not write a line of code that anyone ever sees, the shift in perspective can allow you to play effectively in the developers' sandbox. That is, you need to be seen by developers as a contributor, a peer, an equal, and someone who "gets it." Once you reach this milestone, you're in, and you start to reap the rewards.

But what are the potential benefits of becoming a techie writer? And what are the costs?

Potential Benefits of Being a Techie Writer

Being a techie writer has many potential benefits:

Techie writers are in demand To begin, a techie writer has the potential to be more in demand than less techie writers. Think back to basic economics and the laws of supply and demand. If there are fewer technical writers than technical writers, it stands to reason that the fewer will be relatively more valuable than the latter. And, if you think through the ranks of technical writers you know, you'll quickly note that far fewer have the emphasis on the technical than on the writer.

Techie writers tend to be seen as more valuable, In hiring processes I've been involved with (both formally and as an informal, whatcha-think-Eric consultant), technical skills make a world of difference. A lack of technical skills usually drops a candidate to the bottom of the pile, at least if there are no signs that the candidate is making efforts to change the situation. Raw technical skills with poor communication skills often drops a candidate to a lower spot in rankings; however, setting overall quality aside (as often happens in the real world), it's more likely that a techier individual can hit the ground running and churn out somewhat acceptable content in short order than a less techie individual could do. Thus, the techier candidate is more likely to pop back up to the "interview-again-or-hire" pile as the supply of elusive ideal candidates is determined to be nonexistent. A candidate who demonstrates a good balance of strong technical skills with good communication skills is extremely rare, but often writes his or her own ticket.

Techie writers can demand higher salaries than less techie writers, Taking the Silicon Valley market for example, strong technical skills can return as much as $25-50 dollars more per hour for contractors. That is, an acceptable, moderately senior writer who would bill at $50/hour in most cases could increase the billing rate to $75-$100/hour (at the extreme) with better technical skills. In the full-time permanent arena, the delta can be as much as $20K through $40K annually, plus options, bonuses, and other perks.

Techie writers tend to experience fewer employment delays or gaps, These higher rates can come without unneeded delays in finding work as well. I know of many technical writing contractors who bill upwards of $100/hour through agencies, thus netting around $75-$90/hour, and have less than 10 hours of downtime between gigs. Some Bay area companies are currently paying bonuses of $5000 for referrals for good techie writers. With that level of interest, the downtime between jobs tends to be minimal.

Techie writers can help overcome common workplace challenges, Perhaps just as important, being a techie writer can also improve your work environment. As most practicing technical writers would attest, you don't have to look very far to find developers who have been burned by writers who don't contribute--or worse, who are just plain liabilities--because of an insufficient grasp of the technologies. Once bitten, twice shy, and you'll find that, as a writer, you must first prove that you're not a liability, then start doing your job. That said, if you can speak the language of the developers, work with them on their terms--not yours--and play an active role in getting the product to ship out the door with both solid code and information products, you'll find that your work environment borders on the ideal.

For example, after hiring a new writer, I checked with the lead engineer to find out how the initial encounter went. The engineer said, "She'll be fine to work with. Doesn't yet know it all, but has the background and asks good questions. No problem." So, you think that writer would be complaining about lack of respect? In my experience, you'll have fewer obstacles with the developers if you can speak their language, use their development tools, and understand their processes and challenges.

Techie writers can often work more independently and have more workplace flexibility, Being a techie writer may also offer you more freedom to work independently, effectively, and efficiently than you thought possible. How so? First, if you're willing and even marginally able to get your hands dirty (with code, with hardware, with equipment, or whatever), you gain a great measure of independence. You can test and tinker with the code, you can look and see (and fix) problems that you find (like typos in dialog boxes) and you can insert your own help IDs and help-system hooks, without having to wait for developers to find the time to do so for you. Finally, you can, in general, more easily control your work environment and minimize the time you spend on mundane tasks by automating or eliminating tedious processes.
Second, technical sufficiency may enable you to telecommute or freelance more readily than if you don't have the necessary technical skills to support yourself technical away from the office. Why? Because you are

More valuable to employers, thus they are more willing to accommodate your needs and wishes
More able to support yourself and resolve your own technical issues with little or no help
More able to know when a problem really is serious and requires external intervention

A non-techie writer will often have real difficulties in telecommuting or setting up an independent work environment. Although it is possible for non-techies to telecommute, doing so often requires extensive setup and support, which requires additional resources. Is it worth the hassle to have a less techie writer telecommute? Probably not. If there's no problem or hassle, is there any reason you shouldn't? Good question.

Potential Costs of Being a Techie Writer

Depending on your goals and inclination, however, becoming a techie writer may be costly:

Techie writers may not write as much, The time you spend in honing your technical skills and abilities is time that you necessarily don't spend in honing your writing skills and abilities. For some, that's not a problem. For others, that may mean curbing a passion or inclination for writing and related skills.

Techie writers may be seen as programmer wannabes, Rather than being seen as a techie writer, you may be seen as a programmer wannabe, which can be a disadvantage in all circles. Hiring managers can, in some cases, be threatened or negatively influenced by highly-technical writers, or they might pass over qualified applicants out of fear that they'd quickly jump ship to join the ranks of developers.

Techie writers may not relate to less techie audiences as well, As a techie writer, you can easily lose empathy and understanding for your readers. While acting as a user advocate is nearly always a part of the job description of an effective technical writer, as a techie writer, that will become ever more difficult. Absent conscious effort, you'll eventually forget how hard your technical knowledge was to achieve and how far ahead of your average reader you are.

By: Eric Ray

Tuesday, January 04, 2005

Technical Writing, Code of Good Practice

1- Do not burden readers with information they do not need - they have more than enough difficulties in handling the information they do need.

2- It is the reader's need for information that shall be fulfilled - not the communicator's store of information that shall be emptied.

3- The communicator shall be able to choose freely the means of expression that are the most effective with regard to the reader and the defined goals.

4- The medium is not the message. [I have designed the book, now I shall write it]

5- The communicator is responsible for the intended reader's understanding of the technical message.
An information problem can often be solved in many ways - seldom is only one solution right and all the others wrong.

6- The communicator must not surrender to irrelevant, subjective demands for changes of information.

7- The communicator should make changes in information products only when the alterations increase the effectiveness of the information.

8- It is not unclever to express oneself in a simple way.

9- The communicator must be aware of the legal and moral aspects of his or her communications.

intecom.org