TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:RE: Landed my first job as a technical writer From:"Chinell, David F \(GE Indust, Security\)" <David -dot- Chinell -at- GE -dot- com> To:"Craig Cardimon" <cardimon720 -at- yahoo -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Fri, 17 Nov 2006 14:31:52 -0500
Craig:
A newbie asking for advice! Hold me back!
Fight fires as needed, but be aware that things will never be totally under control. That means you've got to force yourself to set aside regular time for tool development and housekeeping. You probably learned this as a programmer, and it's the same as a writer.
Find material you respect -- maybe publications and online material from reputable software firms -- and use it to guide the development of your techniques and voice. Learn to analyze what others have written to solve your own problems.
Be prepared to rewrite and rewrite and rewrite before anyone else sees your drafts. Don't worry about being able to write it well the first time. Rewrite it into shape.
If none exists, seriously consider creating a house style guide by starting with already written guides and just recording your exceptions to them. You could start with the latest editions of:
- Merriam Webster's Collegiate Dictionary for spelling, usage, and hyphenation
- Microsoft Manual of Style for style issues when writing about software
- Chicago Manual of Style for style issues for all other writing
The critical dimensions of anything you write are: Audience, Purpose, and Subject. If you define these for a topic, chapter, or manual, you'll be able to keep on track and produce a focused, effective information product. Purpose is REALLY important as it defines the scope and context of the information needed.
Wherever possible, create larger works by assembling topics. You could classify topics as being concepts, procedures, or references. Learn what business tasks the reader is expected to accomplish with the product, and write topics that show him how to accomplish those tasks.
I think technical publications are best seen as components of other products. Everything my firm designs has a hardware component, a software component, and an information component. You and I design the information components. Our products should be an integral part of the overall product, not collateral or add-on material.
Now comes the stuff others may find fault with. These are my personal observations. They might seem counterintuitive, but I think they're valuable.
We read with our bodies, not our minds. So all your designs have to accommodate the body, not the mind. We can't reason out what will work for the body, we can only measure what works (or rely on the measurements of others).
There is no meaningful distinction between format and content. Neither exists without the other, and both are equally important in communicating information to your reader. It is helpful to settle on a collection of structures before you start writing, and force yourself to write into those structures, making the content fit them. (The distinction between format and content is artificial and is only valuable when analyzing a work after it has been completed.)
You can't possibly tell anyone the whole story or the complete truth about anything. All you can do is tell them enough to answer the question, complete the task, or understand the concept. Your words will always be an approximation to reality, a simplified model of reality. Your job is to make the model match the reader's purpose. So a reviewer might quibble that you've missed important facts about how the product works, but if those facts don't directly serve the reader's purpose for a given topic or task, you *should* omit them.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
