Download Strategies to Succeed in Technical Writing

Strategies to Succeed in
Technical Writing
By Rob Kurtus (15 November 2004)
Edited By Dale Black (15 October 2005)
Page 1 of 47
TABLE OF CONTENTS
Success Requirements ................................................................................................................................. 4
The Five Powers of a Champion Technical Writer ................................................................................... 4
The Five Powers................................................................................................................................... 4
Roles in Career..................................................................................................................................... 4
Application ............................................................................................................................................ 6
Importance of Health in Technical Writing ................................................................................................ 6
Good Health ......................................................................................................................................... 6
Importance of Good Health .................................................................................................................. 7
Maintaining Health ................................................................................................................................ 7
Importance of Knowledge in Technical Writing ........................................................................................ 7
Knowledge and Skill ............................................................................................................................. 8
Importance of Being Knowledgeable.................................................................................................... 8
Become Knowledgeable ....................................................................................................................... 8
Importance of Excellence in Technical Writing ......................................................................................... 9
Excellent Work...................................................................................................................................... 9
Benefits of being excellent ................................................................................................................... 9
Become Excellent ............................................................................................................................... 10
Importance of Value in Technical Writing ............................................................................................... 10
Valuable Services ............................................................................................................................... 11
Benefits From Being Valuable ............................................................................................................ 11
Become Valuable ............................................................................................................................... 11
Importance of Character in Technical Writing ........................................................................................ 11
Having Character................................................................................................................................ 12
Importance of Character ..................................................................................................................... 12
Maintain Character ............................................................................................................................. 12
Be a Champion Technical Writer ............................................................................................................ 13
Appreciation ........................................................................................................................................ 13
Live As a Champion ........................................................................................................................... 13
Enjoy ................................................................................................................................................... 14
Developing Technical Documentation ........................................................................................................ 15
Conciseness is Key to Good Technical Documentation ......................................................................... 15
Reasons for Wordiness ...................................................................................................................... 15
Technical Documents ......................................................................................................................... 15
How Can You Ensure Conciseness? ................................................................................................. 16
Types of Documentation Needed by Companies ................................................................................... 16
Marketing Material .............................................................................................................................. 17
User Guides and Manuals .................................................................................................................. 17
Administrative Material ....................................................................................................................... 18
Miscellaneous Material for Publication ............................................................................................... 19
The Process of Writing a Technical Manual ........................................................................................... 19
Tasks For a Technical Manual ........................................................................................................... 20
Details on Tasks ................................................................................................................................. 20
Interim Products in Complex Project .................................................................................................. 21
Managing Your Writing Project ............................................................................................................... 22
Get General Requirement .................................................................................................................. 22
Put Together Writing Plan .................................................................................................................. 23
Implement Plan................................................................................................................................... 24
The Role of Technical Writers in Developing eLearning ........................................................................ 24
Background of eLearning ................................................................................................................... 25
Role of Technical Writers ................................................................................................................... 25
Tools and Techniques ........................................................................................................................ 26
Using Tools ................................................................................................................................................. 28
Creating Online Help in RoboHelp from a User Manual in FrameMaker ............................................... 28
Page 2 of 47
Background ........................................................................................................................................ 28
Relationship of Product and Manual .................................................................................................. 28
Converting Files to RoboHelp ............................................................................................................ 29
Developing Help Project ..................................................................................................................... 29
Indexing With FrameMaker..................................................................................................................... 31
FrameMaker Indexing Basics ............................................................................................................. 31
Adding Words ..................................................................................................................................... 32
Editing Existing Index Entries ............................................................................................................. 32
Using RoboHelp to Develop a Simple Web-Based Tutorial ................................................................... 33
Online Help Software.......................................................................................................................... 33
Using as Tutorial................................................................................................................................. 34
Example of Tutorial in RoboHelp HTML ............................................................................................. 34
ISO 9000 documents .................................................................................................................................. 35
ISO 9000 Documents ............................................................................................................................. 35
Who Needs to Know? ......................................................................................................................... 35
Four Tiers of Documents .................................................................................................................... 35
Relation to Compliance ...................................................................................................................... 36
Records Required by ISO 9001 .............................................................................................................. 37
What Is A Record? ............................................................................................................................. 37
Records Required............................................................................................................................... 37
Getting Work As A Technical Writer ........................................................................................................... 39
Skills Required To Be a Technical Writer ............................................................................................... 39
Writing Ability ...................................................................................................................................... 39
Writing Tools ....................................................................................................................................... 39
Product Knowledge ............................................................................................................................ 40
Five Ways to Write Your Way into Technical Writing ............................................................................. 41
1. Get Educated.................................................................................................................................. 41
2. Get Technical ................................................................................................................................. 42
3. Socialize ......................................................................................................................................... 42
4. Show Off ......................................................................................................................................... 43
5. Pound the Pavement ...................................................................................................................... 43
Marketing Yourself as an Independent Technical Writer ........................................................................ 44
Attitude Toward Business ................................................................................................................... 44
Marketing is Important ........................................................................................................................ 44
Marketing Methods ............................................................................................................................. 44
What Technical Writers are Paid ............................................................................................................ 45
Salaries ............................................................................................................................................... 45
Independent Contractors .................................................................................................................... 46
Difference in Location ......................................................................................................................... 47
Page 3 of 47
Success Requirements
The Five Powers of a Champion Technical Writer
(15 November 2004)
A major concept in the School for Champions is that there are five major factors involved in successfully
performing a task or achieving a goal. We call these the Five Powers of a Champion. Applying these
powers will help you advance in your career as a technical writer.
Questions you may have include:



What are the Five Powers of a Champion?
What role does each play in my career?
How can they be applied to advance my career?
This lesson will answer those questions. There is a mini-quiz near the end of the lesson.
The Five Powers
Whenever you set a goal to achieve something, are given a work assignment or are presented with a
challenge, five factors are involved in determining whether you will be successful in the activity.
The Five Powers of a Champion are:





Health
Knowledge
Excellence
Value
Character
Maintaining an attitude of applying these powers to your life and career will allow you to succeed in
achieving your goals.
Roles in Career
Each of these five factors plays a major role in how you will do in your career.
Health
Good health is important in your everyday life. Usually, people take their state of health for granted.
Having an attitude of simply taking care of yourself will do wonders in maintaining your physical, mental
and spiritual health. To be a champion in technical writing, you need to optimize your physical, mental,
and spiritual health.
Physical Health - Writers sometimes abuse their physical health by sitting at their computers too long,
drinking too much coffee, and not getting enough exercise. You should make sure you take care of
yourself. You should also know how to deal with illness or injury by appropriate health care.
Page 4 of 47
Mental health - Within the work environment, you want to avoid situations that cause excess stress.
Continuous unrealistic deadlines, an overbearing supervisor, and excess criticism can affect your mental
or emotional health.
You should be aware of these problems and try to avoid negative situations. Learn to deal with stress
and not to sweat the small stuff. If you can't bear the negative atmosphere around you, seek to move on
to a more healthy emotional environment.
Spiritual Health - Appreciating your blessings and giving thanks for what you have is a positive step in
having good spiritual health. It is a difficult subject to explain, but a feeling of spiritual well-being can give
you greater peace of mind, which will in turn help in the work you do.
Knowledge
A technical writer must have knowledge of writing standards, software tools, and the subject matter. You
must then be able to apply that knowledge as technical writing skills, using the most of your given talent.
Having knowledge and skill in your area of work will give you confidence and sureness in your ability to
do the job. That skill will also give your employer confidence in you.
Excellence
When given a writing assignment, it is important to do your best to deliver a quality product on time. Doing
your best will give you pride in your work and a feeling of esteem. But more important is to make sure you
understand the requirements and specifications from management or the customer. It serves no purpose
to do a good job in something that is not what the customer wants.
Knowing the requirements and then doing a good job on time will satisfy the customer. If possible, exceed
the expectations of the customer and your boss. Your work should then be appreciated, and you will be
looked upon for more good projects.
Value
Your job should provide value to you in terms of wages and satisfaction. That will give you motivation to
work. But to get those rewards, you need to make sure you provide value to your supervisor. The
expression goes: "Your job is to make your boss look good." That is a big factor in getting a raise or
promotion.
Sometimes the supervisor may value other things besides the work done on a project. Often a good
personal relationship is valuable to the supervisor. Technical writers tend to like to concentrate on work
instead of personal relationships. But a good working relationship is often considered valuable to the
boss and should be noted.
Character
Good character traits will take you far. Being courageous to take on difficult tasks and determined to
complete them are important traits. Honesty, integrity and reliability are greatly admired by supervisors
and fellow workers. Finally, the character trait of service and helping others is important.
Having good character allows you to finish tough tasks, to be trusted and admired by the boss, and to feel
you are making a difference.
Page 5 of 47
Application
So, how do you apply these Five Powers of a Champion to advance in your career as a technical writer?
It is all a matter of attitude and keeping what is important in your mind.





Take care of your health to have physical and mental energy
Seek knowledge and learn skills to gain confidence
Do your best to satisfy your customer to be appreciated
Provide value to others to get the rewards you want
Be honest and courageous to be admired
Conclusion
There are five major factors involved in successfully performing a task or achieving a goal. These Five
Powers of a Champion are health, knowledge, excellence, value and character. Having the mind set of
optimizing or applying these powers will help you advance in your career as a technical writer.
Importance of Health in Technical Writing
(Revised 27 April 2003)
In your role as a technical writer, it is important that you are both physically and emotionally healthy. You
can't do a good job at writing, if you don't feel well. Being healthy gives you energy and mental alertness
and allows you to write more effectively. You can maintain your health by taking care of yourself and
avoiding toxic situations.
Questions you may have include:



What determines good health?
Why is it important for a writer?
How can a technical writer maintain his or her health?
This lesson will try to answer those questions. There is a mini-quiz near the end of the lesson.
Good Health
Health concerns both physical and emotional well-being.
Physical Health
Being physically healthy means that your body is functioning as it should, without pain, discomfort, or lack
of capabilities. Causes of ill health include injuries, disease, diet, stress, old age, and genetics.
Emotional Health
Being emotionally or mentally healthy means that your mind and emotions are functioning as they should,
without anxiety, depression or other malfunctions. Causes of mental ill health include physical disease,
stress, genetics and mental abuse.
Page 6 of 47
Importance of Good Health
Being physically healthy is of prime importance in life. Being ill or not feeling well can drastically affect
your work. Obviously, if you feel physically and mentally healthy, you can be more productive, as well as
happier in your writing.
Emotional well-being is also important. Suffering stress, depression, anxiety or other mental or emotional
ailments can affect your work and even your physical health. It is important to be emotionally healthy in
order to write effectively.
Work is only one part of your life. You want to be able to enjoy all aspects of your life and to live a long,
productive and enjoyable life. Being healthy will also allow you to gain knowledge and skills, do excellent
work, be valuable to your employers and be honorable to those with whom you work.
Maintaining Health
Having an attitude of simply taking care of yourself will do wonders in maintaining your physical and
mental health.
Physical Health
Writers sometimes abuse their physical health by sitting at their computers too long, drinking too much
coffee and not getting enough exercise. You should make sure you take care of yourself. You should
also know how to deal with illness or injury by appropriate health care.
A healthy work environment is also important. The "sick building syndrome" can affect people and their
health. If you suspect an unhealthy work environment, speak up or do something to rectify the situation.
Emotional Health
Within the work environment, you want to avoid situations that cause excess stress. Continuous
unrealistic deadlines, an overbearing supervisor, and excess criticism can affect a writer's emotional
health.
You should be aware of these problems and try to avoid negative situations. Learn to deal with stress
and not to sweat the small stuff. If you can't bear the negative atmosphere around you, seek to move on
to a healthier emotional environment.
Conclusion
You want to function properly both physically and mentally or emotionally. Unhealthy habits and stressful
working conditions can affect your health, as well as your ability to write. You should take care of your
health and work environment, so that you can feel good and be productive.
Importance of Knowledge in Technical Writing
(Revised 4 May 2003)
In your role as a technical writer, it is important that you are both knowledgeable and skilled in your
profession. You can't do a good job at writing if you don't know the rules of writing, the subject matter and
Page 7 of 47
how to use writing tools. Being skilled allows you to do your work better and enhances your career. You
gain knowledge through study and skill through application of what you learned.
Questions you may have include:



What sort knowledge is needed?
What are the benefits to a writer?
How can a technical writer become knowledgeable?
This lesson will try to answer those questions. There is a mini-quiz near the end of the lesson.
Knowledge and Skill
Being knowledgeable means you are well informed about writing techniques, the subject matter and tools
to use. This knowledge can come from schooling and more often from on-the-job experience.
Being skilled means you know how to write effectively and to use the available writing tools. It is the
application of your knowledge. This means learning how to write with such commonly used tools as
FrameMaker and RoboHelp.
Importance of Being Knowledgeable
If you know how to write effectively and how to use the required software, you can do your job with less
effort and more quickly. Writing according to the technical writing standards is relatively easy. On the
other hand, it isn't pleasant having to struggle through the process of formatting pages in FrameMaker,
when you really don't know the application.
Also, having knowledge and skill makes you feel better about yourself. Your esteem grows proportionate
to the ease at which you can perform your job.
Being knowledgeable is important in doing excellent work and in being valuable to your employer. That
perceived value can result in raises and promotions. Applying your knowledge helps to show your
character and even helps reduce work-related stress to the benefit of your health.
Become Knowledgeable
The way to gain knowledge in technical writing is to observe, study and read. Writers are known to be
voracious readers. There are good books on technical writing techniques, as well as those on how to use
the various required software applications.
Taking classes and attending seminars on writing topics can add to your knowledge. Participation in
profession organizations such as the Society for Technical Communication (STC) helps you gain
knowledge through their presentations and conversations with other writers. Applying what you have
learned and also analyzing the results of your work are good ways to establish your skills.
Conclusion
Being well informed about writing and subject matters and having skill in using writing tools are important
in being a technical writer. Knowledge can make the work easier, increase your esteem and make you
more valuable to your employer. You should continuously study to improve your knowledge and skills.
Page 8 of 47
Importance of Excellence in Technical Writing
(Revised 26 April 2005)
In your role as a technical writer, it is important that you do your best and produce excellent work. This
will increase your confidence and esteem, as well as result in praise and other benefits. Excellence
requires satisfying the project requirements and going beyond what is expected.
Questions you may have include:



What determines excellence?
What are the benefits to a writer?
How can a technical writer attain this level?
This lesson will try to answer those questions. There is a mini-quiz near the end of the lesson.
Excellent Work
Good technical writing is that which fulfills requirements, is delivered on time and is without errors or
omissions. Excellent writing goes beyond what is required and exceeds expectations. It is synonymous
with quality.
Excellence is in the eye of the beholder. If you have done your best, you may feel your work is excellent.
But if that work is being delivered to someone else, that person may have different expectations and a
different evaluation of whether or not the work was excellent. That is why it is important to know the
requirements and expectations before proceeding on a writing project.
Benefits of being excellent
Benefits of doing excellent work can be an increase in confidence and self-esteem, as well as recognition
and praise.
Confidence and Esteem
It is a good feeling when you complete a difficult writing project. It can increase your confidence in being
able to even more challenging tasks.
If you have done your best, gone the extra mile and produced what you feel is an excellent product or
document, you can feel proud of yourself and your abilities. It is especially gratifying if you can look at a
published, bound document.
Praise
If your supervisor or customer also feels your have done excellent work, you may receive praise or even
special compensation for your work. Your supervisor, the customer and your peers will recognize you as
a writer who does his or her best to produce a quality product. A writer with a reputation for doing
excellent work will certainly advance in his or her career.
Page 9 of 47
Criticism
It is also possible that your supervisor or customer had other expectations or that you did your best, but
the requirements were beyond your skill-level. It is also possible that your supervisor is the type of
person who does not acknowledge excellent work. In such a situation, you may receive no praise or
acknowledgement. In fact, you may even be criticized for the "poor job" you did.
Be Proud
If you feel you did an excellent job, you can still be proud of your work. But you must also evaluate
whether you misinterpreted the requirements and expectations, there were unrealistic demands, or some
personality issues.
Become Excellent
The first thing in ensuring that you do excellent technical communication is to know the requirements for
the documents you are to create. You must then work hard to complete the task on time and per the
requirements, with no errors or omissions.
The attitude of excellence goes beyond simply satisfying customer requirements. It is delivering a
product that is beyond expectations. You should put in the extra touch of quality.
For example, suppose the company wants a training guide written that will be sufficient for the trainer to
use the material. They don't want to spend too much money on the task. If you wrote a document that
was good enough, they would be satisfied. But if you put an extra effort to produce a guide that was
considered well written within the writing budget, you would have a happy customer that would be grateful
for the excellent job done.
Doing excellent work is a natural progression from being healthy and skilled. It leads to being valuable to
your company.
Conclusion
Doing excellent work will increase your confidence and esteem. You may also get praise for your work
and advance in your career. Excellence requires satisfying the project requirements and going beyond
what is expected.
Importance of Value in Technical Writing
(18 May 2002)
In your role as a technical writer, it is important that your work is considered valuable to your supervisor,
company and customer. You can't progress in your career if the work you do is not valuable to others. It
is important to make sure that what you do is valuable and important to your customers. Making sure
management realizes your work contributes to company profits is a way to make yourself more valuable.
Questions you may have include:



What is being valuable?
What benefits do you get as a valuable technical writer?
How do you improve your value?
Page 10 of 47
This lesson will answer those questions. There is a mini-quiz near the end of the lesson.
Valuable Services
A product or service that is valuable to a company is one that is needed to provide a profit or reduce
costs. An important service is one that is critical in the delivery of a product.
A company wants and needs documentation for various reasons. The service a technical writer provides
can be valuable to the company and enhance its bottom line. In many cases, documentation can be
important to the sales of the company's products.
Users or customers may find technical documents useful and important. This means that the writing is
valuable to them. The work you do as a technical writer can also be valuable to your supervisor, who
needs to satisfy requirements on schedule.
Being valuable is a natural progression from being healthy, knowledgeable, excellent and honorable.
Benefits From Being Valuable
By being a valuable and important technical writer to your employer, you can progress in your career.
Employers will compensate a valuable writer, rather than lose him or her to the competition.
There is also the personal satisfaction of being important to the company or the outcome of a project.
Become Valuable
In some cases, where a company or supervisor does not see the value of technical documentation, it is
often necessary to evangelize on the importance and contribution that documentation is to the company's
product. For example, some managers don't realize that a good user manual adds value to the product
and reduces the cost of support.
Once documentation is considered important, you must show that you are a valuable member of the
team. This means to make yourself difficult to replace, as well as directly contributing to the company's
profits. Sometimes a technical writer must do things outside the job description to increase his or her
value to the company. In the long run, the extra work can prove beneficial to your career.
Conclusion
Doing work that contributes to the company's profits makes you valuable and important. Your wages and
career can benefit from being considered a valuable member of the team. To increase your value, you
must seek tasks that will help the company.
Importance of Character in Technical Writing
(Revised 4 May 2003)
In your role as a technical writer, it is important to be have good character. Being honorable and honest
in the work you do and in your relations to others is essential in your profession. Having an honorable
character also provides you with personal benefits and can enhance your career.
Questions you may have include:
Page 11 of 47



What does having character mean?
What are the benefits to a writer?
How does a technical writer show character?
This lesson will try to answer those questions. There is a mini-quiz near the end of the lesson.
Having Character
Having character means that you are honorable and honest, have integrity, and are reliable and
responsible. It also means you are courageous and determined to finish what you started.
On the opposite end of the spectrum, there are people who lie, cheat, or steal. They may also be lazy,
unreliable or inconsiderate of others.
It is obvious that honesty and integrity is important in the workplace. The same is true for reliability and
other forms of character. The technical writer must be ethical and conscientious in his or her writing. This
is especially important when working on a team.
Having an honorable character is a natural progression from being healthy, skilled, excellent, and
valuable on the job.
Importance of Character
Being a person of high character is important in your relationship with other people, your career and your
own self worth.
If you are known as an honest and honorable writer, and a person who is reliable and responsible, those
with whom you deal will be respected you. Fellow workers, supervisors and customers will trust you,
know they can depend on you and want you on their project.
If you are courageous enough to take on a tough assignment and determined to finish it on time, you will
also be respected and admired.
The biggest drawback for writers without positive character traits is that others will shun such a person.
People don't like to work with someone who lies, steals or is lazy.
Another important factor is that the honorable writer has a greater self-esteem. You feel good about
yourself. Finally, there is the religious aspect of being honest, moral and ethical.
Maintain Character
Your actions determine what people think of you and establish your reputation. They also determine how
others will respond to what you do and say.
The way to have character is to always make sure that you are honest, honorable and forthright. Make
sure there is no implication of dishonesty in any form.
You should also seek to be considerate of others and conscientious in your work. This doesn't mean that
you have to be perfect, but it does mean that you are trying to be someone of high character.
Page 12 of 47
Conclusion
A technical writer needs to be honest and reliable. Your reputation affects how people deal with you.
Having good character results in others respecting you and increases your own esteem. Having
character requires a constant effort.
Be a Champion Technical Writer
(Revised 29 May 2004)
Being a champion technical writer doesn't necessarily mean that you are the best there is. Rather, it is
doing your best to achieve your writing goals. This is optimized by following the philosophy of
appreciating what you have, living your life as a champion, and enjoying the adventure of life by helping
others enjoy theirs.
Questions you may have include:



What should be appreciated?
How does one live as a champion?
Why help others?
This lesson will try to answer those questions. There is a mini-quiz near the end of the lesson.
Appreciation
Appreciate and be thankful of what you have, especially concerning your technical writing career. Don't
take your job or business for granted. Even the worst job is better than no job at all.
If you are presently out of work, appreciate your friends and family. Be thankful that you have skills and
abilities. These will all be important in getting your next position.
Live As a Champion
To live your life as a champion means to always seek to stay healthy, knowledgeable, excellent, valuable
and honorable.
Health
You can't write very effectively if you don't feel well. You should take care of your physical and emotional
health, so that you do what you want and need to do. If you are healthy, you simply feel good.
Knowledge and Skill
A writer needs to continually improve his or her knowledge of writing tools and subject matters, as well as
writing techniques. If you are knowledgeable and skilled, your self-esteem will blossom.
Excellence
You must do your best and be able to achieve your goals. Persistence and conscientiousness are
important. If you accomplish things and are excellent at them, you feel confident about yourself.
Page 13 of 47
Value
Technical writers constantly seem to have to sell the value of their profession to management, who often
don't realize that documentation is an extension of the product. You must also make sure you provide
value to your supervisors and customers, such that they feel they are getting their money's worth from the
work you do. If you prove yourself valuable, you feel important and needed.
Character
You must seek to maintain the position of being honorable and honest in your dealing with other people.
In this way, you can hold your head up high and be respected for your integrity.
Enjoy
Life is a journey or adventure. Your chosen profession should also be an adventure, where you reap
rewards and enjoy the trip. Hard work may be necessary, but you don't want to have the attitude that you
are stuck in some drudgery. Enjoy the adventure.
Part of that enjoyment is giving back and helping others to enjoy their adventure. It is often difficult to find
places to help others, so keep your eyes open. Give others at work a helping hand. Be a mentor to
young people. Giving and helping will only increase your enjoyment as a champion in life.
Conclusion
To be a technical writing champion, you should have the attitude of appreciating what you have, you
should live your life as a champion, and help others to succeed.
Page 14 of 47
Developing Technical Documentation
Conciseness is Key to Good Technical Documentation
(Revised 26 April 2005)
One of the most important and difficult parts of technical documentation concerns writing in a concise
manner. Technical writing is different than writing fiction or magazine articles, where a mood may be set
or, in some cases, where space must be filled (people seldom buy thin books).
Effective documentation is important for a business to succeed. This includes both internal documents
and those reaching the customers. Care must be taken in technical writing to avoid unnecessary or nonvalue-added material in the documentation.
Questions you may have on this topic include:



Why is there wordiness?
What is the purpose of technical documents?
How can a writer ensure conciseness?
This lesson will try to answer those questions. There is a mini-quiz near the end of the lesson.
Reasons for Wordiness
Many writers have a love of words and consider themselves artists. Even among professional technical
writers, there are many who are working on a manuscript or screenplay in their spare time.
In much fiction and nonfiction writing, words not only convey information, but they are also used to
present emotions and mood. Often descriptions are used to make the reader feel like he or she is
actually in the scene. Words are used as artistic tools in this type of writing.
On the other hand, the purpose of technical documentation is primarily to communicate required
information.
Technical Documents
Technical documents usually consist of sales and marketing material, user and instruction manuals,
specifications and requirement documents, and online help or web site material.
Sales and Marketing
The purpose of sales and marketing material is to communicate information about the product and/or
services available. There is usually limited space in brochures or advertising material, so the words must
be concise and to the point to get the message across. Clever wording and words with emotional punch
are usually needed.
User and Instruction Manuals
The purpose of user and instruction manuals is to assist the customer in some process. There is also
similar material used internally, including ISO 9000 documentation. The idea is to get to the point in as
Page 15 of 47
few words as possible. This is especially important in long or complex processes. Excess verbiage can
easily result in losing the reader's attention or understanding.
Specifications and Requirement Documents
An important element in specifications and requirement documents is to make sure there are no
misunderstandings. Everything must be concise, and the writer should make sure there are no possible
ambiguities.
Probably one of the greatest problems in trying to be concise in a specification is the use of acronyms.
This is especially true in military documentation, where they sometimes have acronyms made of sets of
acronyms.
Part of this problem comes from the naming of items. In an effort for clarity, items are given descriptive
names of several words. Then, in an effort to be concise, they are made into acronyms. There has to be
a happy medium between conciseness and readability.
How Can You Ensure Conciseness?
There is no "magic bullet" for creating a usable document that is both concise and readable. One method
is to get the idea on paper and write the meat of the content and then edit or prune the document. If you
are a good wordsmith and are thinking in terms of concise writing, you should be able to put things in the
necessary form.
If you are going to be concise in your writing, your words should be well chosen. It is not the time to show
off your vocabulary of esoteric words and obscure acronyms. It takes a tremendous amount of skill and
discipline to select the proper words and describe something in as few words as possible. That is why
good technical communicators are at a premium.
Conclusion
The artistic use of words is best kept to fictional forms. Technical documentation should be concise to
enhance effective communication. Concentrate on providing the best phrases possible to get across the
point in the least words possible.
Types of Documentation Needed by Companies
(Revised 3 May 2003)
Every business--large or small--needs documentation to operate effectively. Requirements for extensive
internal documentation are spelled out in the ISO 9000 series of international standards. The major
classifications of needed documents include marketing, user guides, administrative material and
published works. Technical communicators are needed to write each of these types of documents.
Questions you may have include:



What are marketing copy uses?
Who needs to have user guides and manuals?
What type of administrative material is needed?
The follow explains these types of documentation and the need for them. There is a mini-quiz near the
end of the lesson.
Page 16 of 47
Marketing Material
Companies need written material to provide customers with information about the company and their
products and/or services. The purpose is to make the public aware of what is available, as well as to help
to sell the products. This material includes:



Promotional Brochures
Advertisements, flyers, catalogs, and other pre-sale literature
Informational Brochures
Marketing material has usually been done in slick publications, but recently promotional material and
catalogs have been distributed via CD-ROM. Most companies now use their Web sites as marketing
brochures.
Marketing specialists and advertising copywriters have traditionally done marketing writing. Recently,
professional technical documentation specialists are writing online marketing documents.
User Guides and Manuals
Companies that make products or software need to have manuals and user guides available that will
explain how to properly use the product. These documents are intended for both external customers and
for use internally.
Typical guides and manuals include:




Quick reference guides
Software user or reference guides
Hardware reference and user guides
Combination guides
Many companies are putting their guides and manuals online. Many commercial software companies
have abandoned hard-copy manuals in favor of online help files packaged with the software.
Quick Reference Guides
Quick reference guides provide ready reference to essential features during the use of hardware or
software. They may include graphical devices and other job aides.
Software User Guides
Software user guides provide instructions for using a software product. Since there has been a tendency
to put these manuals online, third-party publishers have been selling such books to satisfy consumer
need.
Software Reference Guides
Software reference guides provide accessible reference information on the features and functions of a
software product.
Page 17 of 47
Hardware/Software Combination Guides
Hardware/Software combination guides provide instructions for using a hardware product and modifying
or programming its firmware/software. Examples include manuals for computer printers, fax machines,
modems and such.
Hardware User Guides
Hardware user guides provide instructions for using a hardware product. "Hardware" means any
electronic or mechanical device, including computers, lawnmowers, and stereo equipment.
Hardware Installation, Reference and Repair Guides
Hardware installation, reference and repair guides provide accessible reference information on the
features and functions of a hardware product. They also explain how to install, modify, maintain or repair
a piece of hardware.
Administrative Material
Most companies need documents to cover various administrative requirements. Such material includes:



Organization manuals
Training materials
Annual reports
The movement is to put much of this material online, on the Web, or on an internal intranet.
Organization Manuals
Organization manuals provide guidance to employees or customers of an organization. They include
policies and procedures manuals, style and identity guides and benefits guides.
Some companies are putting online versions of organization manuals on their intranet. Such
documentation requires an expert in HTML.
Training Materials
Training materials are publications developed for use in a training or classroom environment by either the
trainer or student participant; may include manuals, tutorials, workbooks, and instructor guides.
Computer-based training (CBT), Web-based training (WBT) and eLearning are cost-effective methods of
training over using training manuals and trainers. Most companies tend to outsource the development of
eLearning, as opposed to doing it in-house.
Annual Reports
Annual reports summarize the activities or financial position of a corporation, governmental agency, or
nonprofit community organization.
Page 18 of 47
Miscellaneous Material for Publication
Occasionally, companies want or need other type of writing intended for publication done for them.
These include:




Magazine or trade journal articles
Newsletters
Technical reports
Speeches
Magazine or Trade Journal Articles
A company may want articles published in magazines. This material would include news and information
about an organization, technology, industry, or scientific field. It may be intended for an internal or
external audience, a special interest audience or the general public.
Newsletters
Some companies distribute newsletters giving information about company happenings. Newsletters may
be intended for an internal or external audience.
Technical Reports
Companies may want reports written on scientific or technical efforts. They are usually aimed at the
professional community or a contracting agency.
Speeches
Top company officials may need speeches written for special occasions or presentations. Some
technical writers specialize in this field.
Conclusion
There is a wide range of documentation that companies need for effectively running their businesses.
Documentation is also needed to create new business by providing information to potential customers.
Besides the traditional paper-based documents, online documentation is becoming important to
successful companies.
The Process of Writing a Technical Manual
(Revised 3 May 2003)
The process of producing a technical manual usually is a team effort. In most situations, a Technical
Communicator is only given one portion of the whole project. Other parts go to the Graphical Designer,
Editor and such. The "whole picture" is usually only seen by the Project Manager.
Whether you are doing the whole job, have been assigned a critical part of the project or are managing
the production of the technical manual, you need to know the process involved.
Questions you may have include:
Page 19 of 47



What is the breakdown of tasks on a technical manual project?
What are the details of each of these tasks?
What is the final product from each task?
The following material is an overview of the tasks involved in putting together a technical manual. There
is a mini-quiz near the end of the lesson.
Tasks For a Technical Manual
A standard technical manual is one that is text-based with illustrations. It is usually delivered on paper,
although it may also be an online manual. Technical manuals are usually considered user, service and
training manuals or guides. Marketing material may follow the same steps or tasks as a technical manual
(see Types of Documents Needed by Companies for more information).
The tasks required in producing a standard technical manual are typically:
1.
2.
3.
4.
5.
6.
7.
Research and interview to get information
Outline and organize technical material
Draw or obtain pictures and graphics
Transform technical material into common language
Edit written material
Print and bind manual
Deliver final product
Details on Tasks
What these tasks consist of is fairly straightforward.
1. Research and Interview
The writer must get the necessary information on the subject matter. Some research may consist of
hands-on work. For example, Harley-Davidson Motorcycle Company requires their technical writers to be
able to disassemble and assemble their motorcycles. They also prefer their writers own and drive
Harleys.
Interview SME
Often, the writer must interview the user to find out what is wanted or needed, as well as a subject matter
expert (SME) to get detailed information. When writing software documents, that means interviewing or
talking to programmers. For writing about hardware, the SME may be an engineer, technician or
manager.
The method to interview may be simply talking with the person and taking down notes, or it may involve
tape recording the conversation. A list of questions is often handy to use.
Example Using Video
Sometimes there are other ways to get information. For example, I once wrote a marine transmission
service manual from a videotape of Japanese technicians disassembling and reassembling one of the
company's transmissions. An American engineer explained the operation and gave the names of the
parts on the videotape during the disassembly procedure.
Page 20 of 47
The explanation was then transcribed and edited. Screenshots were made from the video to include with
the steps in the service manual.
2. Outline and Organize
Once your have gathered your research material in the form of notes, transcriptions and documents, you
can organize it. Since technical manuals are usually very logically ordered, outlining the material is a
good idea. In this way, you can modify the order of sections to suit the real need of the document.
There are other ways to organize of technical manual. One common method is to break sections of
material into separate files, either in your word processor or desktop publishing application.
3. Draw or Obtain Pictures and Graphics
A graphic artist or the technical writer may gather pictures and gather or draw illustrations and graphics
for the document. In software user manuals, screen shots are often captured and inserted in the
document. For hardware, photographs may be taken and digitized. A photograph may be used as is or it
may even be changed into a line drawing though the use of graphics software.
One important thing is that you should have a good system for naming and filing your graphics files.
4. Transform into Common Language
Often the experts speak in terms that are not usable in a manual. You want to simplify the language and
to define any acronyms used. It is better to have a document a little below the level of the reader's
knowledge than above what they can understand.
The use of illustrations and graphics helps to simplify the language and to enhance understanding. "A
picture is worth a thousand words."
5. Edit Written Material
Another writer and/or editor, as well as other personnel, should check over the material for content,
grammar, and form. This proofreading is usually an iterative process to fine-tuning the document.
6. Print and Bind Manual
The technical manual is then printed on bound. This may be as simple as making a photocopy or the
pages or of sending the files to a printer to do the job professionally. Since the manual is often going to
the customer, a quality job is worthwhile to enhance perceived value of the product.
7. Deliver Final Product
Delivery of the manual is the accomplishment of your goal. Celebrate that delivery.
Interim Products in Complex Project
In good business practice, the end result of a task is a product delivered. In a complex project, with many
people involved, interim products may be passed from one person to another.
Page 21 of 47
Considering the tasks involved in producing a technical manual, the interim products developed and
delivered in each phase are as follows:






Research and interview document or notes
Material logically organized or outline
Pictures or graphics, organized and entered into document
Text of technical material in common language
Final draft after editing
Packaged product that you deliver
Conclusion
The process for writing a technical manual consists of research, organizing, graphics, clarifying language,
editing, printing and binding, and delivery. One technical communicator may do all of these steps, but
usually it is a team effort.
Managing Your Writing Project
(Revised 6 April 2004)
When you are assigned to a writing project, it is good practice to follow general project management
methods as part of your process. An important part of managing a writing project is documenting all the
requirements and initial factors. You should also document your progress, the outcome and lessons
learned. This will help you in this project and in future writing projects.
Questions you may have are:



What is the general requirement of the project?
How do you do a writing plan?
What are the results of such actions?
This lesson will answer those questions. There is a mini-quiz near the end of this lesson.
Get General Requirement
A writing project usually starts with receiving a general requirement, such as "Upgrade our software's user
manual, including all changes and new features." You may also get a deadline for when the project is
due.
Ideally, you would like to get this information near the beginning of the work on the product, but
unfortunately writers are often brought in almost as an afterthought. This makes it all the more important
to understand the requirement.
Development Scenarios
In the case of a software project, the development manager typically has a specification of product
features wanted. Each feature may be listed as an individual specification, as part of an overall plan of
action. The manager works with the programmers to develop the software. Ideally, the writer should be
involved in this development process, although they are often called in down the road the document what
has already been completed.
Page 22 of 47
Likewise, in the case of writing hardware documentation, the manager works with the engineers on
developing a product according to a specification or technical requirement document. The writer usually
documents how to use or repair the final product, as well as the product's various features.
Know What is Needed
In either case, it is important to know exactly what is needed and to get involved as soon as possible.
Put Together Writing Plan
Once you get the general requirements for the manual that you are to write, you should write up a project
management plan. You need to define the internal and external customers, outline the product definition,
do research and estimate the time needed to do the job.
Define Internal Customer
State who the manager is you must satisfy and who receives the final product. This is the person who is
responsible and who you must make happy.
Define External Customers and Users
State who the external users/customers are and what type of information they need. Knowing the users'
wants and needs is important in delivering a good product. Unfortunately, sometimes what the internal
customer/manager wants and what the external user needs are different. You may discuss the difference
with your boss, but ultimately you have to look to who signs your paycheck or gives your performance
evaluations to determine to whom you listen.
Outline Product Definition
Taking the general requirement and knowledge of what your internal and external customers want, you
can specifically define what product you will be writing and delivering.
In the case of our example of writing an upgrade to the existing user manual, it is a good idea to define
the original manual. If that has never been stated formally, it is a good idea to do that now.
Our original manual consists of:




An installation procedure
Setup procedure
Procedures for using each feature, along with explanations of their functions
Descriptions of all reports that can be printed
The upgrade will consist of:


The original manual
With changes and additions
Do Research
You need to do some research to learn about the product and its features.
Page 23 of 47
As previously stated, the development manager works with the engineers or programmers to build certain
product features. You must understand these features and include them in your documentation. Often
you must interview a subject matter expert to get the information you need.
This all takes time. It is difficult to tell how long it will take you to get the information you need to write
about the product. Even if you are not required to do so, you should keep track on how long it takes you
to get up to speed with your product knowledge, as well as to gain new knowledge.
Of course, as you become more knowledgeable about a product, the research time is reduced.
Estimate Time to do Work
The time it takes to write a document can be split into:







Planning
Research
Write the document
Graphics and special effects
Formatting
Editing
Putting in delivery media
Know what parts of your project are included and give an estimate how long it will take each part.
Implement Plan
Finally, you implement your plan and keep track of your work.
The results of effectively managing your writing project are usually that you get the work done on
schedule, you do the work that is wanted and you have less stress, because the project is under control.
If problems do occur, and they probably will, you will be able to handle or resolve them more effectively.
In general, good planning results in effective management, such that you can do more in a shorter time.
Conclusion
When you get a writing project, you should effectively manage your work. This means to make sure you
understand the requirements and put together a writing plan, where you define the players, define the
product, estimate time to do the job and them implement your plans.
The Role of Technical Writers in Developing eLearning
(Revised 27 April 2003)
Many companies are starting to use eLearning to train their workers, managers, customers and suppliers.
Some of those companies want to use their internal technical communicators or writers to not only write
the content, but also to develop the CBT or WBT. This may present a new challenge to the writers.
Questions you may have are:

What is eLearning?
Page 24 of 47


What techniques and writing skills are needed?
What types of tools are used in developing eLearning?
The following material will try to answer those questions. There is a mini-quiz near the end of the lesson.
Background of eLearning
Companies are looking for cost-effective ways to increase the training of their workers and managers.
Some are also seeking to provide more training to their customers and even suppliers. Standard
classroom training can be expensive when employees have to take time off from work. If travel is
necessary for the training session, cost may rise even further.
Solution is eLearning
A valid solution is eLearning, which primarily covers Computer-Based Training (CBT) and Web-Based
Training (WBT). Online tutorials and online help for software products are also sometimes included as
part of eLearning.
Delivery Methods for eLearning
CBT is usually delivered on a CD-ROM, while WBT is obviously delivered over the Internet. Online help
is traditionally delivered with the software application.
Several years ago, CBT titles were developed on high-end authoring applications such as Macromedia
Authorware and Asymetrix Toolbook. Authorware is still being used, especially since it allows streaming
of audio and video files through the popular Shockwave plug-in. Meanwhile, Asymetrix changed their
name to Click2Learn and seem to be phasing out Toolbook.
Present Trend
The present trend is to develop the eLearning material that is browser-based, such that it may be
distributed both on a CD-ROM and online. Interactive material is often done in Macromedia Flash. The
CD-ROM version may include more audio and video, while any testing and certification would be done
over the Internet. Even online help is going online. At the very least it is HTML-based.
Role of Technical Writers
Companies typically use their training personnel and instructional designers to develop and write the
training material. With the emergence of eLearning, many companies are increasing the role of technical
writers to development and writing process.
Role Expanded
The role of the technical writer or technical communicator has expanded from being someone who can
write well and can effectively gather information from subject matter experts, to a person who can not only
write technical copy but can also use sophisticated tools to publish the material online.
Page 25 of 47
Must Know Tools and Techniques
Knowing how to use such programs as FrameMaker, RoboHelp, Acrobat, and some graphics and
illustrator programs as PaintShop Pro, Photoshop or Illustrator is no longer enough. The technical writer
must now learn how to develop web pages and eLearning material and use the tools required for those
tasks too.
Tools and Techniques
The writer must learn to use the special tools employed in developing eLearning. This includes
instructional design software, course management tools, web page tools, and even some multimedia
applications.
Tools
There are a number of tools that can be used for developing eLearning.
Instructional Design
A solid approach to developing eLearning is to follow instructional design principles. A top tool for this
task is Designer's Edge from Mentergy. This application leads the development manager, designers and
writers through a series of steps and includes forms to fill out.
Course Management and Testing
Graded testing for certification cannot be done off a CD-ROM. It must be controlled and done online. An
application for managing a course and providing controlled tests is ASPTESTS, developed by Lanex.
Besides managing the course, it provides templates for creating test questions, choices and correct
answers. Groups of questions can be randomly displayed so that students will not be able to "fudge"
tests through repeated entries.
Tools for Developing Web Pages
The major applications for developing web pages and web sites are Microsoft FrontPage and
Macromedia Dreamweaver. FrontPage is easier to use, but Dreamweaver is more sophisticated and
assures the pages won't be only Microsoft-specific.
The Coursebuilder add-on to Dreamweaver helps to add quizzes and interactivity to web pages.
Macromedia Flash is also used to develop animations that download quickly on the Web.
Writing techniques
In developing eLearning, you should follow good instructional design, planning the needs and knowing
the audience, before writing the material.
Following Design Steps
Well-designed instructional material is thoroughly thought out. First, management determines their
requirements. They analyze needs, draft a mission statement, create an audience profile, and write
objectives.
Page 26 of 47
Then the writer can proceed in a step-by-step manner:
1.
2.
3.
4.
5.
6.
7.
8.
Outline content
Lay out course map (with Training)
Define treatment
Select learner activities (with Training)
Storyboard course
Produce media (with Graphics Design)
Author course and write content
Test and evaluate course material
Need Special Writing Skills
Each of these areas requires special writing skills. The writer certainly needs the ability to outline and
organize the content of the course and to write a treatment or a short essay that defines what the course
is all about. The writer also needs to be able to layout the instructional material as a storyboard. This
can be similar to script writing.
Online Help Mind-Set
Writing the content requires the same mind-set as used in writing online help. Short sentences should be
employed and there should be not too much material on a page or screen. More can be learned in small
chunks and users prefer not to have to scroll much.
Conclusion
Companies are employing technical writers to develop eLearning, working alongside trainers and
instructional designers. The role of the technical writers is expanding, and they must learn to use new
web-based tools, as well as to learn new techniques for writing eLearning material.
Page 27 of 47
Using Tools
Creating Online Help in RoboHelp from a User Manual
in FrameMaker
(Revised 24 March 2001)
Many technical communicators are tasked with converting user manuals and other documentation written
in Adobe FrameMaker into online help using Macromedia RoboHelp. The problems they face concern
not only going from FrameMaker to RoboHelp but also how to put the content in a form that is effective for
online help. The solution is not difficult, provided the writer follows a methodical approach.
Questions you may have include:



What do you need to know before converting the manual?
What is the process of converting to RoboHelp?
What is a way to develop a help project?
This lesson will answer those questions. There is a mini-quiz near the end of the lesson.
Background
After writing a large user manual in FrameMaker for a Wisconsin-based software company, they decided
they needed online help for their software product and wanted it done in RoboHelp. This paper provides
a case study of the process used to create online help for their product, including the relationship of their
product and its user manual, how I converted FrameMaker to RoboHelp, and how I developed online help
content from the user manual.
Relationship of Product and Manual
It is important to know what the product does and what its user manual is supposed to achieve before
proceeding to the development of the online help.
Job Costing Product
The user manual was written for a job costing software application. This product helps service
companies-such as in the construction industry-monitor the costs of their projects. It allows managers to
keep track of such items as material, labor, and subcontractor fees. The application's menu system is
arranged according to job cost functions or activities of the user. The menu opens numerous windows or
forms for entering or viewing data.
This is a complex application that allows the user to drill down on data in a window and go to subwindows for further detail. There are over 200 windows available for displaying job data, and each
window requires its own procedure in the user manual. The structure of the manual is based on the
hierarchical arrangement of the application's menu system.
User Manual in FrameMaker
The FrameMaker book was divided into files for each of the major areas of the menu, such as job
maintenance, entering transactions and viewing job status. This arrangement-with the descriptive naming
Page 28 of 47
of the files-was also applied to the help project. The continuity of file names used in the manual and
online help proved useful in keeping track of material.
The purpose of our user manual is to show how to use the numerous job costing windows, as well as the
navigation between them. The manual is approximately 450 pages long and has over 250 sections.
Most of those sections include a procedure, with several screen shots. When put into WinHelp, each
section results in one or more help topic.
Before starting, special paragraph styles were used in the FrameMaker book to maintain consistency and
to aid the documentation, and fonts were selected for aesthetic appeal. During the writing, words and
phrases were marked for indexing. This was very important, since the index is the most used feature of
online help. Indexed items in FrameMaker automatically follow the conversion into RoboHelp.
Converting Files to RoboHelp
The process of converting a book written in FrameMaker to the format suitable for using with RoboHelp is
relatively straightforward. It consists of converting the FrameMaker files to Microsoft Word and then
reformatting the text in Word to make it easy to use in RoboHelp.
Converting FrameMaker Files to Word
If a FrameMaker file has any pictures or graphics included, you cannot easily convert that file to Word.
Since our manual includes numerous screen shots, as well as small graphics to indicate such things as
mouse movement and warnings, it was necessary to strip all of them from each FrameMaker file. Many
of those graphics would probably not be used in the online help or would not fit into the help format, so
their removal was not a problem.
Once the graphics were removed, I simply saved the files as Word files. The process was painless,
unless a graphic or two was accidentally left in. Since I had previously named the FrameMaker files to
reflect their function, the name of the Word files would remain the same.
Reformatted Files For Use in RoboHelp
Paragraph and font styles from FrameMaker files carried over into Word files. When a Word file is then
converted to RoboHelp, the existing font sizes and types are maintained. Each heading is automatically
changed to Heading 1 and is made a topic title for the online help.
I wanted to get rid of all the paragraph styles used in the FrameMaker files and make the Word file as
"clean" as possible. That may not have been necessary, but I felt getting rid of all the old baggage would
prevent potential problems. I changed all the styles, except the headings, to Normal with a font of Arial 9.
This would conform to the style commonly used in WinHelp. I also changed all the heading files to Arial
12 for automatic topic construction in RoboHelp.
Developing Help Project
Once the files were converted to Word, I created a help project, selecting the WinHelp 2000 option in
RoboHelp version 7. Two important innovations in this help project were using the outlining feature of
Word to aid in organization and changing major procedures into graphics with popup explanations.
Page 29 of 47
Used WinHelp 2000
We decided to use the WinHelp 2000 feature of RoboHelp 7 instead of the standard WinHelp 95 format,
since that is the look of the future. WinHelp 2000 appears like Microsoft's HTML Help, which is used in
Window 98 and Office 2000 products. The only difference-which is also an advantage-is that WinHelp
2000 is still based on the Windows 95 help engine, thus avoiding possible compatibility problems.
WinHelp 2000 seems easier to navigate than WinHelp 95 since the contents are always available in what
they call the Explorer view. Another big advantage of using WinHelp 2000 is that online help is easier to
create. You do not have to designate the type of window that a jump goes to. Secondary windows are
not used in WinHelp 2000.
A nice feature in WinHelp 2000 is that you can add a graphic as a watermark to your non-scrolling areas.
I inserted the company logo as a watermark, such that it displayed to the left of every topic title. A
disadvantage of WinHelp 2000-as well as HTML Help-is the fact that the help window is typically much
larger than in WinHelp 95 and often covers the view of your application.
Outlined Word Files
When you create a new topic in RoboHelp, the topic title becomes Heading 1 in Word. I wanted to be
able to distinguish between major sections and their subsections when working in Word, to aid in the
organization of my material, but I did not want those topics to look any different in the online help. I used
the outline feature of Word, changing the headings of subsections all the way down to Heading 4. This
made the section organization very similar to the user manual.
I reformatted the font style of Headings 1 - 4 to be 12 point Arial. Thus, I could examine the outline in
Word and easily reorganize the position of the files. This would not affect anything in the online help, but
it made it easier to keep things in logical order. I also made the headings light blue to add a little pizzazz
and to look good with the company logo in the non-scrolling area of the topic window.
Went From Procedures to Pictures
In trying to simplify our procedures for filling out the various job-costing windows, I realized that in many
cases using procedures was not the best way to do things. Also, some of the procedures were well over
10 steps long, which makes them difficult to follow.
Look to User's Needs
I realized that the user does not need numbered instructions to fill out text fields or to click on certain
buttons. Rather, the person would like to know what specific items mean and what happens if you use
the item. Thus, I decided to replace major procedures with a reduced size picture of the window in
question and use popup windows to explain each item in the window. Some of those popup windows
would include a jump to another topic or choices of other popup windows for more detail.
Outlined Popups
After it was made into a topic in RoboHelp, each popup window was outlined, as a Heading 6 in Word
and the font was set as Arial 9 bold. The "keep with next" paragraph feature was turned off for the popup
titles to display in the help. The popup windows were listed under their topic, making them easy to find
and edit in Word.
Page 30 of 47
Used Reduced Screen Shots
Using the screen shots of the Advanced Job Cost windows with popup windows proved to be a very
effective way to provide help to the user. A major outcome of this idea was the realization that perhaps
our user manuals weren't explaining the material in the best way possible. Also, perhaps online help
would be a better medium for giving the information the user really needed.
Conclusion
FrameMaker files can be converted to Word files suitable for use in RoboHelp by several methods. With
this version of FrameMaker, it is necessary to remove all graphics from the document before converting.
Another method, which is less tedious, is to copy and paste sections. FrameMaker styles can be
removed from the Word file to reduce clutter. RoboHelp's WinHelp 2000 is a good option for getting the
HTML Help look but still using the WinHelp 95 engine.
Using outlining in Word can be helpful in keeping your material organized, provided all heading font styles
are the same for topic titles. Developing online help can give you insight on a better way to structure your
information. In the case of the help for this job costing application, screen shots with popup windows of
the various items proved an effective way to assist the user.
Indexing With FrameMaker
(14 July 2000)
Indexing a document is an art in itself. Since Adobe FrameMaker is the program of choice for most
companies producing technical documentation, it is worth while to find out how to create an index in
FrameMaker.
Questions you may have are:



What are some indexing basics?
How do I add words as new index items?
How do I edit existing index items?
The following material is explains how to use FrameMaker for indexing your document. There is a miniquiz near the end of the lesson.
FrameMaker Indexing Basics
The index is an alphabetically arranged list of key words and reference pages. FrameMaker keeps track
of each entry, its associated words and the page with a marker. Entries with the same text are merged
into a single entry with several page references. In some cases, a number of entries may all start with the
same word. In such a case, sub-entries can be entered, as seen below. You can also have a crossreference to another entry, as well as a range of pages.
advertising
classified,
selling services,
selling space,
marketing
121,122
108,459,473
94,96,97
21-22
Page 31 of 47
Adding Words
The method to add words is fairly straightforward.
1. First, show text symbols: View > Text Symbols. This allows you to see the markers.
2. With your mouse, highlight the word or words to index.
3. Open the Marker window: Special > Marker. Make sure the Marker Type is Index. The
highlighted words will be automatically entered in the Marker Text field.
4. Edit or add text. (See next two sections).
5. Click New Marker button.
Using Multiple Entries Per Marker
You can add several entries in one Marker window be separating entries with a semi-colon (;). For
example, if your entry was economic advantage, you may also want to include an index entry of
advantage, economic.
Thus, you would include in the Marker Text field: economic advantage;advantage, economic. You
could have any number of entries, as deemed appropriate.
Adding Sub-entries
If you realize the first word in an entry is used in numerous other entries, you could place the next words
as a subentry. You do this by separating the words with a colon (:).
For example, if your entry was open book and you know there are several other entries starting with
open, you could make book a subentry: open:book.
Of course, care must be taken to make sure your entries make sense.
Editing Existing Index Entries
You can easily find and edit existing index entries.
1.
2.
3.
4.
5.
6.
7.
Show text symbols: View > Text Symbols.
Open the Marker window: Special > Marker.
Open the Find/Change window: Edit > Find/Change.
Select Marker of Type: in the Find drop-down list box.
Type index in the Find text box.
Choose the Find button. The next index entry will display in the Marker window.
Edit entry and click Edit Marker. To delete, enter Space + Backspace.
Printing Out Chapter Index
You can view or print the index for individual chapters in your FrameMaker book. This facilitates editing,
as opposed to using the book's whole index.
1. In the file or chapter you are editing, File > Generate/Book to open the Generate/Book window.
2. Mark the Index radio button and choose the Generate... button.
3. The index for the chapter is generated and displayed. Print the chapter index to examine and edit.
Page 32 of 47
Conclusion
The process for creating and editing an index in a FrameMaker document is relatively simple. The
greater task is deciding on what to index for effective use by the readers.
Using RoboHelp to Develop a Simple Web-Based
Tutorial
(Revised 4 May 2003)
RoboHelp is a top application for developing online help. It is also used for developing Web-based help,
such as JavaHelp and RoboHelp's WebHelp. Besides being used for online or Web-help, RoboHelp can
also be used to develop simple tutorials.
Questions you may have include:



Why use RoboHelp instead of other Help applications?
How can this program be used to develop a tutorial?
What would it look like?
This lesson will answer those questions and help you understand this useful method. There is a mini-quiz
near the end of the lesson.
Online Help Software
The top applications for developing online help are RoboHelp and Doc-to-Help. Both are good and have
similar features and capabilities. Each is expensive enough to discourage the casual user. There are
also some other less expensive--but not very popular--programs available.
Industry Standard
Since RoboHelp is apparently the "industry standard" in the technical documentation arena, this lesson
will concern using it, as opposed to one of the others. The principles used are similar in all of the
applications, provided they have the same capabilities and features used.
RoboHelp HTML
RoboHelp Office consists of the standard RoboHelp, used for developing WinHelp, and RoboHelp HTML,
which allows you to develop HTML Help, JavaHelp and WebHelp.
HTML Help is the format Microsoft is now using in their Office 2000 products. It consists of a
compressed file that explodes into a series of HTML help files.
WebHelp is a form of HTML Help provided in RoboHelp HTML, without the compressed file, thus making
it suitable for use on the Internet. WebHelp can be delivered as DHTML or Java-based.
JavaHelp is a format that is used in few applications and is completely based on Java.
Page 33 of 47
Using as Tutorial
There is a slight difference between online help and a tutorial. Online help is usually logically arranged in
a table of contents, but its index feature is most often used to find words and expressions of which the
user is unsure.
On the other hand, a tutorial is usually linearly ordered, with no need to jump around. The help system
can be effective for simple tutorials. The outline paradigm, with the contents in little books on the side, is
handy for the user to locate special areas in the tutorial.
Example of Tutorial in RoboHelp HTML
The following is an example of a tutorial developed in RoboHelp HTML's WebHelp. It goes through the
steps required to develop that tutorial.
First try the DHTML version. If your browser does not accept DHTML, try the Java version, which takes
somewhat longer to download. Study the example and then complete this lesson.
Developing Tutorial in RoboHelp HTML. (DHTML version)
Developing Tutorial in RoboHelp HTML. (Java version)
This same tutorial is also available as a standard HTML page. Since this is a very short tutorial, the
HTML version is actually easier to use. With more complex subjects, the online help versions may be
more effective.
Developing Tutorial in RoboHelp HTML (Standard HTML page)
Conclusion
You can use RoboHelp HTML or other online web-based help development tools to create simple online
tutorials. They have the familiar help look to them and are easily navigated.
DHTML-based WebHelp Tutorial
Java-based WebHelp Tutorial
Page 34 of 47
ISO 9000 documents
ISO 9000 Documents
(Revised 10 March 2001)
There are four tiers of documentation recommended for satisfying ISO 9000 requirements. These
documents are: the Quality Policy Manual, Procedures, Work Instructions, and Records.
Questions you may have include:



Who needs to know about these documents?
What are the characteristics of each?
How do they relate to ISO 9000 compliance?
This lesson will explain these four types of documentation. There is a mini-quiz at the end of the lesson.
Who Needs to Know?
A number of people within a company should be familiar with these documents and their requirements.
Upper Management
Since ISO 9000 starts with upper management, they should be aware of what types of documentation is
needed to assist in keeping their business well-organized.
Head of Quality
The Head of Quality in a company is often in charge of controlling these documents and specifying the
requirements for them, so obviously that person needs to be familiar with what they are about.
Technical Writers
The technical writers, or others who are assigned to write these documents and manuals, need to be fully
aware of their significance.
Workers
Finally, the workers who may use the documents as guides, or who may have to fill in records, must know
about the ideas behind these ISO 9000 documents, as well as the significance of them to the company
and their jobs.
Four Tiers of Documents
The four tiers of ISO 9000 documentation are the Quality Policy Manual, Procedures, Work Instructions,
and Records.
Page 35 of 47
Quality Policy Manual
The Quality Policy Manual (also simply called Quality Manual) is a top-level document that states the
company philosophy toward providing quality product and work. It states what you plan to do. Since it
states the company philosophy and outlines how the business is to be run, it should be written in direct
coordination with top management.
Doomed to Failure
Companies that do not have direct involvement of their executive officers in the drafting of the Quality
Policy Manual are doomed to failure—at least in the proper implementation of ISO 9000.
Needs Mission
The Quality Policy Manual usually includes the policy toward each of the ISO 9000 requirements. This
goes beyond simply re-stating the requirement. Instead it needs a mission and vision from management.
Rationale or Belief
My personal approach toward the Quality Policy Manual is to add the rationale for each policy in the
manual. In other words, I believe you should include the reason for a given policy in order to show how it
will benefit the company, its operations, and its profits.
Procedures
A Procedure Manual should state how you plan to implement the policies stated in the Quality Policy
Manual. It also states who is responsible for each ISO 9000 section.
Procedures often involve several departments or work areas within a company. They often outline the
work flow between departments, suppliers, and the customer.
Work Instructions
Work Instructions involve the details of how an individual or group is to perform a specific task or job.
This is very important to maintain uniformity, as well as to ensure that the job can still be done if a key
employee is unavailable.
Records
Record keeping is certainly important to track design, costs, work, and product. The records should be
value-added. Some poorly-run companies are careless in keeping records, while others keep
unnecessary records.
Relation to Compliance
If a company is well organized, it is less likely to be involved in foolish mistakes or to have dysfunctional
areas within the company. Thus there is a great need for some standards of organization.
By following the ISO 9000 standards, along with having a good company policy toward quality,
procedures that tell what will be done and who will do it, work instructions to assure consistency of
operations, and solid record-keeping, a company can enhance its chances for success.
Page 36 of 47
Conclusion
The documentation required to operate a business effectively and satisfy ISO 9000 requirements are a
Quality Policy Manual, Procedures, Work Instructions, and Records. A company that does this will
enhance their chances for success.
Records Required by ISO 9001
(Revised by Mohsin Nishat - 14 April 2001)
ISO 9000 requires that records be kept of critical operations. Record keeping is the fourth tier of required
documentation in ISO 9000, following the Quality Policy Manual, Procedures, and Work Instructions.
Questions you may have include:



What is a record?
What are the required records?
What is the reason for these records?
This lesson will answer those questions. There is a mini-quiz at the end of the lesson.
What Is A Record?
Records consist of any historical documentation, such as summaries or meetings and reviews,
specifications, invoices, results of tests and such. This is different than procedures and instructions that
tell what do to. Instead, a record is the history of what has been done.
Records Required
The following lists the records required under ISO 9001 version 2000, along with the referring subparagraph number from the standard. ISO 9002 and ISO 9003 would be subsets of this list. Of course, a
company may choose to include additional records that they deem important.
Para.
Record Required
5.6.1
Management reviews.
6.2.2 (e)
Education, training, skills and experience.
7.1 (d)
Evidence that the realization processes and resulting product fulfill requirements.
7.2.2
Results of the review of the requirements relating to the product and actions
arising from the review.
7.3.2
Design and development inputs.
7.3.4
Results of design and development reviews, and any necessary action.
7.3.5
Results of design and development verification, and any necessary action.
7.3.6
Results of design and development validation, and any necessary action.
7.3.7
Results of design and development changes review, and any necessary action.
Page 37 of 47
7.4.1
Results of supplier evaluations and actions arising from evaluations.
7.5.2 (d)
As required by the organization to demonstrate the validation of processes where
the resulting output cannot be verified by subsequent monitoring and
measurement.
7.5.3
The unique identification of the product, where traceability is a requirement.
7.5.4
Customer property that is lost, damaged, or otherwise found to be unsuitable for
use.
7.6 (a)
Standards used for calibration or verification of measuring equipment where no
international or national measurement standards exist.
7.6
Validity of previous results when measuring equipment is found not to conform
with its requirements
7.6
Results of calibration or verification of measuring equipment.
8.2.2
Internal audit results.
8.2.4
Evidence of product conformity with the acceptance criteria and indication of the
authority responsible for the release of the product.
8.3
Nature of the product nonconformities and any subsequent actions taken,
including concessions obtained.
8.5.2
Results of corrective actions.
8.5.3
Results of preventive actions.
Reason for Records
The reason to keep records is for future use as a reference in case of questions related to contractual and
legal matters, work techniques, verification of work done, and other parts essential to the company
running smoothly. The company management should use sound judgment as to what records are nonessential and how long to keep a specific record.
Conclusion
In order to operate a business effectively, you should keep records of essential activities. To become
certified under ISO 9001, there is a specific list of records that need to be maintained. Even if your
company is not planning on being certified, this is a good list to follow.
Page 38 of 47
Getting Work As A Technical Writer
Skills Required To Be a Technical Writer
(Revised 27 April 2003)
There are special skills needed to become an effective technical writer that go beyond basic writing
ability. These skills include the ability to write lucidly and concisely, familiarity with the writing tools of the
trade, and understanding the technical subject matter or product line.
Questions you may have are:



What sort of writing ability is necessary?
What tools do I need to know?
How much product knowledge is required?
This lesson will explain what special skills are required to become a technical writer. There is a mini-quiz
near the end of the lesson.
Writing Ability
Many technical writers majored in technical communications, journalism or English in college. This
indicates an ability to write, although it does not necessarily give them an edge in technical writing. One
of the biggest problems some English majors have is that their writing is more artistic than technical.
They write with feeling instead of concise description.
Other technical writers come from engineering, marketing, and education fields. They usually gravitate to
technical writing because they enjoy the writing process. Technical writers with backgrounds in
Information Technology are among the most concise and proficient, and therefore in higher demand.
The main talent needed is the ability to explain or describe processes in a concise and professional
manner. Being a wordsmith and good editor is important.
Writing Tools
Being skilled-or at least familiar-with the standard writing tools is very important in getting a job or being
successful in technical writing. A good idea is to look at the want ads in the newspaper to see what
writing tools are required for most jobs. Often knowledge of tools is listed as a requirement before writing
ability.
Word Processor
Microsoft Word is the standard word processor used by most companies, although there are exceptions.
Skill in Word is useful, but since most word processors are so similar, it is not that difficult to migrate from
one to another.
Desktop Publishing
The industry standard desktop publishing application right now is Adobe FrameMaker. Companies that
use the MAC may require Quark.
Page 39 of 47
The main reason for moving to desktop publishing programs is not to employ fancy design, such as is
used in magazines. Rather it is to create large documents that include pictures and graphics. Large
documents become too cumbersome with a word processor.
Distribution
An additional part of desktop publishing concerns distribution. Adobe Acrobat is the standard means of
distributing documents on disk or online. It is not difficult to use, but many companies desire knowledge
of the application.
Online Help
Ehelp's RoboHelp is the most popular Windows Help authoring tool, with Doc-to-Help a distant second.
Both require knowledge of Word.
Online help requires different writing skills than needed to write a user manual. The material must be
much more concise, with short sentences. Procedures should have a maximum of five steps. Indexing is
also very important in online help, since the index is the way most people find their help information.
Graphics
Many technical writing jobs now require the ability to also do graphical design. There does not seem to
be a real standard in this area, although many use Corel Draw or Adobe PhotoShop. Companies that are
heavy into graphics usually are MAC shops.
Web Pages
Many companies are now requiring technical writers to develop web pages. The most common tool is
Macromedia Dreamweaver. Ability to use graphical tools is useful, as is coding in HTML.
Writing for web pages is similar to writing for online help. Wordiness is not encouraged.
Product Knowledge
You have to write about a product or a process, so it is important to have knowledge in that field. In many
cases, you interview subject matter experts for details, so at least you should be able to understand the
material to ask the right questions and to relay that information into your document. It also helps if you
like what you are writing about.
An interesting note is that Harley-Davidson Motorcycle Company requires that their technical writers are
able to disassemble and assemble one of their motorcycles. You have to be a special person to write for
them.
Conclusion
Ability to write concisely, knowledge of writing tools and understanding of the product are necessary skills
for becoming a technical writer.
Page 40 of 47
Five Ways to Write Your Way into Technical Writing
By Sean Hower (26 August 2001)
Even with the technology market slowing down, there is still a need for quality technical writers. Technical
writers produce documentation that describe products or services and explain how to use them. While this
field may seem out of reach, becoming a technical writer is pretty easy.
There are five methods you can use to break into technical writing:
1.
2.
3.
4.
5.
Get Educated
Get Technical
Socialize
Show Off
Pound the Pavement
This article explains each of these methods. While they are presented as separate methods, you should
try all of them in order to maximize your hiring potential. There is a mini-quiz near the end of the lesson.
1. Get Educated
Employers want people with degrees. If you're in college now, it's the best time to get the education you
need.
Types of Degrees
Employers look for people with degrees in English, engineering, computer science, or communications.
They also take people with degrees in "related fields" (the definition of “related” will probably vary from
company to company). A growing number of universities are beginning to offer degree programs in
technical writing, or in the very least offer it as a minor usually as a part of an English degree. If you don't
want a degree in these fields, you should at least take some classes in grammar, communications, and
engineering.
Certificate Program
If you've been through college, you can always sign up for a certificate program in technical writing.
These are offered through universities or colleges. These programs teach you technical writing basics
and introduce you to the software that technical writers use. You can also take extension courses that
will teach you a variety of practical skills you'll need in the workplace.
Books on Writing
If you don't have the time or money to take a certificate program, you can always buy books. Technical
writing books are usually in the "writing skills" or "learning to write" sections of your local bookstore. They
cover a variety of topics from very general overviews about technical writing, to designing specific forms
of documentation with a specific type of software. The Idiots Guide to Technical Writing and Technical
Writing For Dummies are great introductory texts to the field and tell readers what to expect from a career
in technical writing. Developing Quality Technical Information is a great book that details some of the
theory and practice behind producing technical documentation.
Page 41 of 47
Go Online
If all else fails, you can go online. There are a host of web sites out there that will teach you the skills
you'll need more or less for free! Use your favorite search engine, do a search for "technical writing" or
"technical communications" and start browsing. The best place to start is TECHWR-L (pronounced techwhirl). This site provides a newsletter, list server, articles, tutorials and links. You can take a look at my
web site as well. I am constantly adding new information for writers.
2. Get Technical
Technical writers use a variety of software to produce documentation. The most common programs are
Adobe FrameMaker, Adobe PageMaker, Adobe PhotoShop, eHelp's RoboHelp and Microsoft Word.
Other common programs include Visio, Doc-to-Help, ForeHelp and Illustrator.
If you haven't checked around, let me tell you now that this stuff is pricey, reaching as high as a few
thousand dollars. Purchasing any of these programs is clearly out of the question for most people. The
problem is, employers look for experience in these programs. What can you do?
Well, don't worry. First, if you're a student you can usually buy software at a discounted student rate. It's
usually a pretty sizable deduction, which makes the software generally affordable unless you are a
starving student. Second, you can always pick up how-to books that come with demo or shareware
versions of the software they deal with. Make sure demo or shareware versions are included before you
buy anything though. Some companies put try-out versions of their software online. You can download
these try-outs for free, but the try-out period usually runs out in 30 days. Finally, if you know someone
who owns the software you want to learn, ask if you can use his or her computer some time.
3. Socialize
Let's face it, the most common way people get a job is by knowing someone. Luckily, there are
organizations and web pages that can point you in the right direction to meet the people who can help
you land a technical writing job.
STC
The Society for Technical Communications (STC) is an international technical writing organization. Many
large cities in the US have local chapters. You can visit their web site. Membership dues runs $125 for
non-students, and $45 for students.
Your dues allow you to receive the STC's monthly magazine as well as its quarterly journal Technical
Communication, both excellent publications with news and research in technical writing. You'll also be
able to attend local STC meetings at a discounted rate, where you'll meet other technical writers and be
able to start networking.
Mentor
A good way to socialize, and get educated, is by finding a mentor. You can do this through the STC, or
through any of a number of technical writing web sites.
Page 42 of 47
4. Show Off
Okay, so you've learned some software and picked up some technical writing basics. You're ready to
start sending out resumes, right? Wrong. You'll want to put together a portfolio of some sort first. Your
portfolio is your chance to show what you know, what you have done, and what you can do.
You can make a few small samples that demonstrate your ability using try-out copies of software or
freeware downloads. These samples might include an online help project, a multi-chapter document,
some graphics or animation you've created or even your own web site. If you have none of these, you
can always include some of your best work from school. Whatever you use in your portfolio, make sure it
is your best effort, it functions properly, and above all that it's professional. A mentor can be of great help
in helping you put together a portfolio.
5. Pound the Pavement
Once you've put together a portfolio, it's time to start sending out resumes. There are several things you
can do at this point, each of which has its drawbacks.
Local Companies
First, you can go to the hiring page of local companies and see if they are in need of technical writers.
The problem with this is that some companies do not list all available jobs. A position might also be filled
before you even notice it's been posted.
Send Resume
A second option is to send out your resume to every company that would need a technical writer, whether
they have an opening posted or not. This gets your resume on file and you might luck out when the
company starts looking for new writers. This is a time consuming process, though, and it may not yield
any results at all.
Online Job Boards
Another avenue to take is to use online job boards. These web sites not only allow you to post your
resume on the web, they also maintain databases of thousands of jobs you can browse through based on
any criteria from location to salary range. There are tons of these sites to choose from. The best are
Dice and Monster.
While these job boards are great tools, they have a few drawbacks. First, most of the jobs are for
contract positions that last anywhere from a few weeks to a year. Second, a small number of jobs posted
are not real. Contracting firms post these jobs in order to gather resumes for their own portfolios. This
means you might be wasting some of your time responding to fictitious leads.
Conclusion
While there is no guaranteed way to land a job, the methods I've discussed will definitely help you out.
Remember that while doing any one of these methods will increase your chances of breaking into
technical writing, doing them all will be a great boost to your career.
Page 43 of 47
Marketing Yourself as an Independent Technical Writer
(Revised 3 May 2003)
Some technical writers go into business for themselves as freelancers or independent contractors. A
number of those become successful enough to form a writing company and hire a staff of other writers.
In either case, the technical writer who is self-employed must continually perform marketing to maintain a
steady income.
Questions you may have about this are:



What attitude is required to be a freelancer?
How essential is marketing?
How should marketing be done?
This lesson will answer those questions. There is a mini-quiz near the end of the lesson.
Attitude Toward Business
You should look at yourself as a viable business, even if you are just getting started in working
independently. Give your business a name. Get business cards and even stationery. You can buy blank
business card sheets at an office supply store and print your own cards. Likewise, you can make your
letterhead from your home computer. Just make it look like you are serious about being in business for
yourself.
Never call yourself a freelancer. That implies you are writing as a hobby. If you work alone, say you are
a "one-person business" or say, "I have a writing business".
If you are getting jobs through a consulting firm or job shop, where you become a temporary employee of
the firm, say you are subcontracting. The attitude of being in business for yourself is essential.
Marketing is Important
Marketing is a most important part of being a business. It should not be thought of as some chore to
perform.
Continue to do marketing, even with clients you worked for before. Send out your brochure, a newsletter
or give them a call every so often. Don't take clients for granted.
Above all, ask clients for referrals. If they liked your work, they will either pass your name on to others or
give you a lead. They should know you are looking for more work.
Marketing Methods
Do some research and find organizations for which you are interested in working. Don't make cold calls.
Rather try to get contacts before calling on a potential client.
Have a portfolio and give presentations. Call up potential clients and say, "May I meet with you to show
you my portfolio?" When meeting with a potential client, tell the stories behind the publications in your
portfolio, explaining the challenges you faced and how you resolved them.
Page 44 of 47
Be enthusiastic about your work. Tell the person, "We'd love to work with you." Your enthusiasm can be
contagious and will also imply you do good work. Leave samples behind when you are done with a
presentation or meeting with a client.
Conclusion
Have an attitude that you are a viable business. Enjoy marketing and let others be aware you are looking
for business. Be prepared when you go in for an interview.
What Technical Writers are Paid
(20 April 2002)
The amount of money paid technical writers for their services varies considerably with location. Writers in
Northern California top the list with an average of $86,000 per year, while writers in Wisconsin and Utah
are at the bottom at an average salary of around $48,000 per year. People interested in making technical
communication as a career can use this information as a guide in for what to expect in this industry.
Present writers can use the information to see where they stand in comparison to the norm.
Questions you may have are:



What are the salaries in my location?
What are independent contractors paid?
Why is there such a difference in location?
This lesson will answer those questions. There is a mini-quiz near the end of the lesson.
Salaries
The mean or midway salary for a technical writer in the United States in 2002 is $55,000 per year and the
average is $65,000 per year. This is considering all levels of experience and locations.
By Location
The median salaries by location in the United States in 2002 are:
State or Area
Yearly Salary
Northern California
$86,000
Massachusetts
$74,000
Connecticut
$69,000
New Hampshire
$68,000
New Jersey
$67,000
Southern California
$67,000
Virginia
$65,000
Oregon
$65,000
Washington
$65,000
Colorado
$64,000
North Carolina
$53,000
Page 45 of 47
Texas
$64,000
New York
$64,000
Georgia
$63,000
Maryland
$62,000
Florida
$62,000
South Carolina
$63,000
Illinois
$60,000
Minnesota
$52,000
Arizona
$60,000
Pennsylvania
$58,000
Ohio
$54,000
Indiana
$54,000
Arizona
$53,000
Missouri
$52,000
Michigan
$52,000
Wisconsin
$48,000
Utah
$47,000
By Years of Experience
The median salaries (for all locations combined) by experience are:
Years
Yearly Salary
Less than 2 years
$42,000
2 to 5 years
$48,000
6 to 10 years
$57,000
Over 11 years
$63,000
Independent Contractors
Writers who are in business for themselves are paid at a higher rate, but they must also pay for their own
health insurance and benefits out of their wages, as well as paying extra business taxes. Many such
independents establish themselves as a limited liability company (LLC) or as a corporation.
Other independents work through consulting agencies that "hire" them on a per-job basis. They often get
health insurance and have their taxes deducted, but they usually get less money per hour of work.
Yearly earnings
The mean yearly earnings before deductions are:
Yearly wages
Range of earnings
$64,000
$30,000 - $120,000
Working through an agency $59,000
$31,000 - $101,000
Independent contractors
Page 46 of 47
Hourly rate
The mean hourly rates for these writers are:
Hourly rate
Range of rates
$45
$25 - $70
Working through an agency $37
$22 - $55
Independent contractors
Difference in Location
A major factor on wages is supply and demand, although a subtler factor concerning technical writing is
the attitude toward technology and the value of writers.
Northern California is the home of Silicon Valley and thus has a large number of software and technology
companies that need good technical writers. On the down side is that the cost of living is high, finding
affordable housing is difficult, and commute times are long. Also, with the recent dot-com and technology
downturn, jobs may not be as stable in that area.
The Boston area has many software companies and is booming in the high-tech industries. There is also
a positive attitude toward technology people, as opposed to lower end states such as Wisconsin.
States near the bottom of the rung typically emphasize agriculture or heavy industry and often don't need
or use writers. Companies that do use technical writers in those states have a greater supply of local
writers than demand and thus do not need to pay very much compared to the rest of the nation.
Conclusion
Pay varies considerably according to location. Knowing the typical salaries in your area can help you
negotiate a reasonable salary.
Page 47 of 47