Discussion on:
View:
Show:
I'm just wondering if do we really need a programmer to become a technical writer. Also, where can I get a sample project timeline with specific tasks for the tecnical writer?
As a programmer married to a technical writer, I can tell you that most large development projects need a good technical writer. First, do not hire a programmer as a technical writer. Programmers understanding coding, not grammer. Secondly, as stated at the end of the article, technical writers need to have the same understand as the programmers. Technical writers should be involved in the whole process of the project, especially when developing specifications, designs, and testing. A goodtechnical writer will also be a good tester for your software.
In general, if you have an unknown software product, one of the best ways to get it known is by having good documentation. Thus, a good technical writer will be a very valuable assetto this type of work.
In general, if you have an unknown software product, one of the best ways to get it known is by having good documentation. Thus, a good technical writer will be a very valuable assetto this type of work.
technical writing really isn't that hard.
In my shop the core developers take the first stab at explaining the flow and then someone with better communication skills and a solid tool like robohelp puts it together. no mess no fuss.
In my shop the core developers take the first stab at explaining the flow and then someone with better communication skills and a solid tool like robohelp puts it together. no mess no fuss.
I wonder just how effectively your documentation meets your user's needs? Have you done a survey to see if they use it, and if they do use, how useful they find it?
Writing a manual or developing a help system means more than just printing a definition of a field, but means that providing examples, and link to related fields...or providing the procedure for the task. Maybe your developers have good writing skills, in which case your company is *very* lucky, but from what I've seen, it takes more than "someone with better communication skills" to "put it together."
I am a technical writer, and I spend hours working with the program to see what information I can extract from it, as well as meeting with programmers, customer care, and others to pull all the information together. Then, I have to analyze how the information is going to be used, and by whom, to ensure utmost accessibility.
It's a long task that requires asking good questions, listening carefully, writing well, and being flexible to meet the needs of multiple groups.
It's not easy...it's a frustrating job, but one I wouldn't give up for the world.
Writing a manual or developing a help system means more than just printing a definition of a field, but means that providing examples, and link to related fields...or providing the procedure for the task. Maybe your developers have good writing skills, in which case your company is *very* lucky, but from what I've seen, it takes more than "someone with better communication skills" to "put it together."
I am a technical writer, and I spend hours working with the program to see what information I can extract from it, as well as meeting with programmers, customer care, and others to pull all the information together. Then, I have to analyze how the information is going to be used, and by whom, to ensure utmost accessibility.
It's a long task that requires asking good questions, listening carefully, writing well, and being flexible to meet the needs of multiple groups.
It's not easy...it's a frustrating job, but one I wouldn't give up for the world.
In most cases, having the engineer/developer/programmer create the documentation isn't cost-effective and isn't going to result in ?good documentation?. I can?t begin to tell you how many times I?ve heard an engineer say ?you don?t need to put thatin the manual? because they know the product inside out but haven?t any idea how a clueless bowb is going to screw up trying to figure out how to use their baby.
I?ve often described a big part of my job as ?professional clueless idiot?. Does it mean that I don?t understand the technology?? Nope, not even close. I?ve got an extensive technical background and can take apart and put together any of the physical products I?ve worked with and I?ve written software that went into the product suite because the engineering staff was too busy to do it. However, it?s important for a technical writer to adopt a na?ve, PeeWee Herman attitude toward the product and its documentation. What are the stupid questions some of these morons are going to ask? If our documentation doesn?t answer their questions, they?re going to call tech support. Just like a programmer has to make sure that the program isn?t going to crash and burn if some moron puts numbers in a field designed for alpha characters, we tech writers have to make sure we?re answering even the simple questions that have (to us) obvious answers. If we do that, we?re serving the best interests of the customer.
I don?t tout my lack of knowledge of a specific technology as a good thing. What I do tout is my ability to adopt the wide-eyed wonder of a completely clueless new user. If I don?t have any current knowledge about it the product or technology, I?ll be able to be a member of the support team by the time I?m done with the manual and/or help file. I may even be acting in that capacity to a certain extent.
I?ve often described a big part of my job as ?professional clueless idiot?. Does it mean that I don?t understand the technology?? Nope, not even close. I?ve got an extensive technical background and can take apart and put together any of the physical products I?ve worked with and I?ve written software that went into the product suite because the engineering staff was too busy to do it. However, it?s important for a technical writer to adopt a na?ve, PeeWee Herman attitude toward the product and its documentation. What are the stupid questions some of these morons are going to ask? If our documentation doesn?t answer their questions, they?re going to call tech support. Just like a programmer has to make sure that the program isn?t going to crash and burn if some moron puts numbers in a field designed for alpha characters, we tech writers have to make sure we?re answering even the simple questions that have (to us) obvious answers. If we do that, we?re serving the best interests of the customer.
I don?t tout my lack of knowledge of a specific technology as a good thing. What I do tout is my ability to adopt the wide-eyed wonder of a completely clueless new user. If I don?t have any current knowledge about it the product or technology, I?ll be able to be a member of the support team by the time I?m done with the manual and/or help file. I may even be acting in that capacity to a certain extent.
The sad fact is that most people wouldn?t recognize ?good? documentation if it bit ?em in the ass. I can take documents that were created by engineers/programmers and pour ?em into my desktop publishing program of choice, clean ?em up a little bit and print ?em out and folks will look at ?em and ooh and aah over ?em and said they were wonderful. The fact is they were still poorly written and incomplete? but they were pretty and looked professional so the folks thought they were wonderful. I do that as a stop-gap measure that takes me all of about an hour so that if we we?re going to publish crappy documentation, at least it?ll look professional and not embarrass the company in the marketplace.
From that point, I get to work and start withthe miserable excuse for documentation they give me and add all of the stuff they left out, eliminate the stuff they didn?t need, rewrote all of the drivel, reorganize it so that it has a structure that makes sense, and fix it so there are cross-references, appropriate illustrations, a dynamically-generated table of contents and index.
Then when I got done, I ask folks to review my version against the original version they thought was so good. At that point, the sun begins to peek over the horizon and folks begin to realize the value that a top-notch technical writer can bring to an organization.
From that point, I get to work and start withthe miserable excuse for documentation they give me and add all of the stuff they left out, eliminate the stuff they didn?t need, rewrote all of the drivel, reorganize it so that it has a structure that makes sense, and fix it so there are cross-references, appropriate illustrations, a dynamically-generated table of contents and index.
Then when I got done, I ask folks to review my version against the original version they thought was so good. At that point, the sun begins to peek over the horizon and folks begin to realize the value that a top-notch technical writer can bring to an organization.
The original article has some good points and questions to ask when hiring a writer. But there are some incorrect things, too.
First, if your staff authors its own documentation, do you really want them to? Are you paying them to develop a product or to write? I've worked with very few--two--programmers who could also write.
Second, if you want a writer who can "act independently and not rely too much on internal resources" you're probably going to end up with mostly useless documentation. Agood technical writer becomes part of the project and brings some unique gifts to the project. Act independently, yes. But a writer relying on internal resources is just as important as a programmer relying on them. The writer is part of a team, andthat means working together.
As to the ignorance is an asset myth, well, I think it has been misunderstood, or more accurately, used as a bad marketing tool by some technical writers. Being able to look at a function, a feature, a product from the standpoint of an "ignorant" user can be an asset. Knowing what questions and preconceptions a user might have can help in the writing. Programmers and project managers are often too close, too knowledgeable about a product to be able to think likea user who doesn't know every detail about your product. A good technical writer can ask the questions that your user will ask, know *how* such a user will approach the product.
Unfortunately, the technical writing field has no real standards orcertification. Anyone can call himself a technical writer. And they often use the "ignorance is an asset" line to get you to hire them.
If a potential writer is more interested in fonts, design, page layout, and the like, chances are they know the mechanics of writing but not how to write technically.
just some random thoughts...
First, if your staff authors its own documentation, do you really want them to? Are you paying them to develop a product or to write? I've worked with very few--two--programmers who could also write.
Second, if you want a writer who can "act independently and not rely too much on internal resources" you're probably going to end up with mostly useless documentation. Agood technical writer becomes part of the project and brings some unique gifts to the project. Act independently, yes. But a writer relying on internal resources is just as important as a programmer relying on them. The writer is part of a team, andthat means working together.
As to the ignorance is an asset myth, well, I think it has been misunderstood, or more accurately, used as a bad marketing tool by some technical writers. Being able to look at a function, a feature, a product from the standpoint of an "ignorant" user can be an asset. Knowing what questions and preconceptions a user might have can help in the writing. Programmers and project managers are often too close, too knowledgeable about a product to be able to think likea user who doesn't know every detail about your product. A good technical writer can ask the questions that your user will ask, know *how* such a user will approach the product.
Unfortunately, the technical writing field has no real standards orcertification. Anyone can call himself a technical writer. And they often use the "ignorance is an asset" line to get you to hire them.
If a potential writer is more interested in fonts, design, page layout, and the like, chances are they know the mechanics of writing but not how to write technically.
just some random thoughts...
Thanks guys for the vote of confidence. I do feel everyone thinks they can write technically but few can. It is an art form and a talent.
It's correct to desire a confident tech writer with a background in programming but my experience is few programmers (or for that matter most people who are involved in the project so close up) have the ability to see the larger picture or act as a replacement for the user. Important details are not communicated because the programmer knows it so well. Let's not forget the standard thought that the technical writer is the inital representative for the end user. As such ignorance is bliss.
However, as a senior tech writer I've found it useful to be both a "technie" that is, understand the logic of code. Additionally, one's mind must be linear and be able to document the necessary steps to be taken for the user to get from point A to point B. As I like to tell people, does one know exactly how an ATM works to get one's money from the machine? No, just to understand the screen prompts and what buttons it expects you to push.
miami tech writer
It's correct to desire a confident tech writer with a background in programming but my experience is few programmers (or for that matter most people who are involved in the project so close up) have the ability to see the larger picture or act as a replacement for the user. Important details are not communicated because the programmer knows it so well. Let's not forget the standard thought that the technical writer is the inital representative for the end user. As such ignorance is bliss.
However, as a senior tech writer I've found it useful to be both a "technie" that is, understand the logic of code. Additionally, one's mind must be linear and be able to document the necessary steps to be taken for the user to get from point A to point B. As I like to tell people, does one know exactly how an ATM works to get one's money from the machine? No, just to understand the screen prompts and what buttons it expects you to push.
miami tech writer
Our Metrology organization spends close to a million each year on hard copy and automated technical bullitens and manuals. The only combination of skills that allow us to accomplish this herculean task is to hire someone with extensive knowledge ofmetrology, theory of operation,hands on, and the written english language.
Programmers and engineers are notoriously inept at putting their thoughts on paper in a way that the non-programmer/engineer user can understand. Technical writers must beable to fully understand the process and system they are describing to the user public and they must have the formal concrete skills of the english language to construct clear and concise text.
Programmers and engineers are notoriously inept at putting their thoughts on paper in a way that the non-programmer/engineer user can understand. Technical writers must beable to fully understand the process and system they are describing to the user public and they must have the formal concrete skills of the english language to construct clear and concise text.
Having been a technical writer/curriculum
developer for 25+ years in more than a dozen
industries, I've learned to conduct a similar
interview in reverse -- do I really want to work
with a bunch of hackers (SEI level - total chaos)
or a team that understands software life cycle
processes and uses them to accelerate design,
implementation, testing, etc. (SEI level 3 or 4).
If you really want a professional technical
writer, get one who knows the value of a
documentation planand can write one from scratch.
If you really want a waste of time and money, wait
until the software is in its final test phase
before you hire a writer; them pressure him/her
with a release date that guarantees a lousy job.
In between these extremes, there are varying
levels of foolishness and good business. If you
assume your customers won't read the documentation
anyway, don't bother with a professional writer,
because even an experienced pro won't be able to
overcome contempt
developer for 25+ years in more than a dozen
industries, I've learned to conduct a similar
interview in reverse -- do I really want to work
with a bunch of hackers (SEI level - total chaos)
or a team that understands software life cycle
processes and uses them to accelerate design,
implementation, testing, etc. (SEI level 3 or 4).
If you really want a professional technical
writer, get one who knows the value of a
documentation planand can write one from scratch.
If you really want a waste of time and money, wait
until the software is in its final test phase
before you hire a writer; them pressure him/her
with a release date that guarantees a lousy job.
In between these extremes, there are varying
levels of foolishness and good business. If you
assume your customers won't read the documentation
anyway, don't bother with a professional writer,
because even an experienced pro won't be able to
overcome contempt
I've been creating technical documentation for more than 10 years as both a full time employee of the company and as an outside resource. My experience has been that documentation is usually an afterthought for most managers, although more and more business are recognizing the importance of what good documentation means both internally and externally.
I believe that a good technical writer plays just significant of a role in the team as a good developer does. After all, a developer is hired to code software or an engineer to design hardware, not to write documentation. Ask those people and that is most often their response. The purpose of a technical writer is to perform the function of creating documentation while the other team members perform their responsibilities. Everyone works as a team to complete a common goal. Besides, having a developer or engineer write documentation is usually not cost effective or done to the level of the intended audience.
For those involved in project management, documentation should always be considered as a part of the overall project plan no matter how insignificant it may be. On most large projects, a technical writer or writers can contribute early on to create design documents and continue contributing along the way to end user documents or training material. The earlier in a project that a technical writer gets involved, the less impact on others time is required. What may be more important and a cost savings is the result of morethorough and comprehensive documentation.
I believe that a good technical writer plays just significant of a role in the team as a good developer does. After all, a developer is hired to code software or an engineer to design hardware, not to write documentation. Ask those people and that is most often their response. The purpose of a technical writer is to perform the function of creating documentation while the other team members perform their responsibilities. Everyone works as a team to complete a common goal. Besides, having a developer or engineer write documentation is usually not cost effective or done to the level of the intended audience.
For those involved in project management, documentation should always be considered as a part of the overall project plan no matter how insignificant it may be. On most large projects, a technical writer or writers can contribute early on to create design documents and continue contributing along the way to end user documents or training material. The earlier in a project that a technical writer gets involved, the less impact on others time is required. What may be more important and a cost savings is the result of morethorough and comprehensive documentation.
It seems like documentation has been lumped into one category. I've been writing engineering specs for years and they are great for those that need to reference them for writing tests or generating a user's manual. I would look towards a technical writer to do a user's manual since that is were things need to be explained in plain english with just the necessary facts and in an esthetically pleasing format. I can't because I've been using 'shall' and listing details too long. Sometimes the people using my documents become a techincal writer/reviewer for my documents if they understand the level of detail of the document because they may need clarification that will cause me to modify how something is stated. Again, I think intended audience plays would guide you to make the decision to hire and or not.
Look to those that are in the business of doing it and doing it right. Essential Data Corporation is the best answer in the industry
The disconnect between the hiring organization and the tech writer is further exacerbated, when the writer comes in through a middleman. While it's a win-win situation for all parties when an unemployed writer gets a task quickly through a staffing firm. The only downside is the communication gap that occurs. As a writer, I've seen it all. I've had to learn new technologies, statistical concepts, pharmaceutical dictionaries on the fly. Did I know these were the specific requirements of the job? No. I bent over backward to learn and perform AND deliver on time. All that towards what end? The hiring party looks at the money they're paying the staffing firm without looking at the progress made by the writer. They get another writer and repeat the vicious cycle. That's when things go south. It's just bad karma--all around. Let's break the cycle. Let's stick with a writer; learn to look past the mistakes; invest in technology training. Forget the money you paid the staffing firm; it's a sunk cost anyway. (Just a few thoughts from a disillusioned technical writer.)
- Keyboard Shortcuts:
- Prev
- Next
- Toggle
