Technical Writer Career Guide

Technical Writer Career Guide

Join Our Happy Customers

1 Share this book:


Contents

Contents 2
Introduction 5
Chapter 1. Technical Writing Industry 7
What is Technical Writing? 7
Understanding Technical Writing 7
Who Does Technical Writing? 8
What Industries Use Technical Writing? 9
Ready to Start Technical Writing? 9
History of Technical Writing 10
Antiquity 10
Middle Ages 10
Renaissance 11
Age of Reason 11
XX Century 12
Nowadays 13
The Purpose of Technical Writing 14
Chapter 2. How to Become a Technical Writer? 15
How Do I Become a Technical Writer? 15
What Skills Does a Technical Writer Need? 15
Freelance vs. a 9-5 Job 16
Who Needs Technical Writers 17
11 Skills of a Good Technical Writer 19
Writing skills 19
Technical Writer Career Path 26
Education and Background 26
Career Opportunities 27
Advancement Opportunities 27
5 Simple Steps to Build a Career in Technical Writing 29
Practice 29

2 Share this book:


Consider Open-Source Projects 30
Stay in the Loop 30
Get Certification 30
Differentiate Yourself from Other Technical Writers 31
Over to You 31
Technical Writer Job Challenges 32
Making It Simple versus Being Specific 32
Knowing Where to Get Data 33
Knowing What Needs to Be Said, and How 33
They’re an Essential Part of the Team 33
Chapter 3. Tools & Tips 35
Free Tools for Technical Writers: Video & Image Editing 35
FastStone Image Viewer 35
LICEcap 37
Advanced Image Editing - GIMP 40
Free Tools: Community & Social Networking 42
AddThis - Social Tools 44
SurveyMonkey 45
Summary 48
Free Tools for Technical Writers: Statistics & Analytics 49
6 Tips For Online Documentation Design 54
Target Specific Audience 55
Follow The Trends 57
Do Not Overcomplicate 59
Responsive Is The New Sexy 60
Awesome Fonts And Where To Find Them 63
The Beauty and the Speed 65
Online Help Design Tips 66
3 Ways To Create Documentation Color Scheme 67
Use A Template 67
Go Corporate 68
Creating Color Schemes From Scratch 69
Color Theory Basics – Color Wheel 70

3 Share this book:


Free Color Scheme Resources 72
Chapter 4. You Are Hired. What’s next? 80
How To Optimize Documentation Team Workflow 80
Your Typical Team 80
Your Typical Workflow 81
Two Steps for Optimization 81
Create a Documentation Plan 81
Use Help Authoring Tools 82
Conclusion 82
Documentation Team: How to Delegate Tasks 84
The Basis of Delegation 84
The Five Steps of Delegation 85
It’s About Trust 86
Cross Team Communication for Technical Writers 87
Tech Writers Are Full-Fledged Members of the Team 87
Communication Is Everything 88
Optimize the Process 88
It Works to Your Benefit 89
Conclusion 90

4 Share this book:


Introduction

Every day each of us makes many decisions that depend on technical
information. Whether it’s about a new device, software or some
other piece of tech, or maybe a medical treatment - all these things
are always accompanied by some sort of instruction. These
instructions provide help on how to perform a particular task, deal
with a problem, use the product safely, etc. All kinds of documents
that help people interact with technology and solve problems are
examples of technical writing.

Technical writing is a writing niche specialized in explaining how
things work, and helping others to perform specific tasks and to
accomplish selected goals. Technical writers create different types of
procedural or “how to” documents like user manuals, product
descriptions, project reports, white papers, information
presentations, instructional texts.

The demand for technical writers is on the rise nowadays. The good
news is that technical writers are required in almost any industry,
from construction to food processing and preservation. So if you are
particularly talented when it comes to breaking down complex
processes into easy-to-understand articles, then technical writing
might be the right niche for you.

5 Share this book:


In this career guide1, we’ve compiled our personal experience and
the very gem pieces of advice gathered throughout our 10+ years
careers in the field of technical communication. We hope that this
book will help you make up your mind about taking a path of a
technical writer, switching from another career into technical writing
or further develop as a professional.

For more stories for technical writers, web developers and web
designers willing to grow subscribe to our blog and follow us on
Facebook, Twitter, Medium.

Good Luck with your technical writing!
ClickHelp Team

1
D
isclaimer: This e-book is designed for information purposes only. The publisher and the
author(s) is not engaged to render any type of psychological, legal, or any other kind of
professional advice. The content of each article is the sole expression and opinion of its author(s)
and publisher. No warranties or guarantees are expressed or implied with this e-book. Neither
the publisher nor the individual author(s) shall be liable for any physical, psychological,
emotional, financial, or commercial issues, including, but not limited to, special, incidental,
consequential or other issues. You are responsible for your own choices, actions, and results that
might arise due to the use or misuse of this e-book.

6 Share this book:


Chapter 1.
Technical Writing Industry
What is Technical Writing?

Each of us makes many decisions that depend on technical
information. Whether it’s about a new device, a software or some
other piece of tech, or maybe a medical treatment - all these things
are always accompanied by some sort of instruction. These
instructions provide the end-users help on how to perform a
particular task, deal with a problem, use the product safely, etc. All
kinds of documents help people interact with technology and solve
problems are examples of technical writing.

Technical writing is a key competence for anyone working in science,
engineering and other technology-relevant spheres. These fields deal
with different kinds of reports and pieces of documentation. This is
where technical writers step up and do their job. But what is
technical writing anyway?

Understanding Technical Writing

Technical writing belongs to the broad field of technical
communication. Technical communicators include technical content
developers, technical editors, technical proofreaders and other
professionals. The word “technical” here is what matters. Unlike
other writers and content creators, technical writers are like
translators: they have a piece of technology and their task is to
explain to a non-expert how to use it in clear, accurate and
easy-to-understand writing.

7 Share this book:


Unlike other sorts of writing, the goal of technical writing is to
communicate complex information clearly and precisely for the
audience and the purpose at hand. To make information clear and
concise, the use of p lain language i s recommended.

There is a common misconception that technical writing is as simple
as sitting down at a computer and writing. But in reality behind every
documentation project is a lot of effort and complexity.

Who Does Technical Writing?

When technical writing was only taking roots, it was mostly engineers
who wrote the documentation about how to use, maintain or repair
particular products. As long as engineers are no writers, those
manuals were bulky binders that were hard to read.

8 Share this book:


The need for this kind of specialists grew, especially after WWII, when
a lot of machines, weapons, medical equipment and other
technologies were invented. Then in 1980 the U.S. Department of
Justice announced technical writing a profession.

Today’s technical writers develop different kind of documentation.
These include user manuals, product descriptions, project reports,
white papers, information presentations, instructional texts and
other sorts of writing. Technical documentation is being delivered as
printed or/and online content. It often includes visuals, audio,
animations, instructional videos and other aids.

What Industries Use Technical Writing?

Technical writing is a part of most careers. Can you imagine a field
which doesn’t require any instructions, reports, procedures, or
descriptions? For example, if you are a manager, then you write
memos, personnel evaluations, all sorts of reports, and also most
likely give presentations. Or if you are a medical professional,
psychologist, or accountant, than you keep precise records which are
also examples of t echnical writing.

Full-time technical writers work in a wide range of industries:
software. E-commerce, networking, bioengineering, science,
medicine, manufacturing, etc.

Ready to Start Technical Writing?

Technical writing skill is in high demand nowadays. It is not only a
full-time position, but also is a part of many careers. In order to be
competitive in your profession or in a field of technical

9 Share this book:


communication you need to acquire particular skills such as plain
writing. Or maybe we’ve inspired you to b
ecome a technical writer?

History of Technical Writing

Let us consider the tools that can be used to check how your online
documentation looks like on a wide screen and on a mobile device.
All the mentioned tools are totally free, and that’s so nice!

Technical writing has been around for a few centuries. It is a field
that demands a specific set of skills for technical communicators to
have. Throughout the centuries, technical writers served as
mediators between people, who created technology and people who
used technology. But where does technical writing come from? How
old is it?

Antiquity

It all started in classical antiquity. The earliest examples of technical
writing belong to Aristotle (384–322 BC). Archaeologists managed to
retrieve short examples of his technical writings, including a
dictionary of philosophical terms and a summary of the “Doctrines of
Pythagoras”. Aristotle’s works are considered the earliest forms of
technical writing.

Middle Ages

The first example of a technical document published in English was
created by Geoffrey Chaucer (1343–1400). It was a scientific treatise
on the astrolabe — a device used for measuring the distances of
stars, planets etc. and for calculating the position of a ship. That work
brought him fame during his lifetime as an author, philosopher and
astronomer.

10 Share this book:


An astrolabe — a device used in the past for measuring the distances of stars, planets
etc. and for calculating the position of a ship

Renaissance

During the Renaissance, the theoretical knowledge of the Antiquity
had been applied practically. Many inventions, including that of the
mechanical printing press in the 15th century, created a need to
chronicle new technologies. Famous inventors and scientists like
Leonardo da Vinci (1452 – 1519) and Isaac Newton (1642–1727)
compiled documents with their inventions and findings. Those
documents played a crucial role in developing modern forms of
technical writing and communication.

Age of Reason

More complex inventions had been made during the Industrial
Revolution. However, at that time, only the inventors themselves
knew how to use their new machines. The innovations waited to be
tested and implemented into the daily life, but in order to do that
people needed to learn how to use them. Unlike the past, when skills
were handed down through oral traditions, the writers who could
document these devices were desired.

11 Share this book:


XX Century

The golden age of technical writing began with World War I, when the
nuclear technologies had been updated and the advances in
medicine and aerospace technologies had been made. This rapid
growth and the urgency of war created a need for documents that
chronicled the use of these technologies.

After World War II, technological advances led to an increase in
consumer goods and standards of living. During the post-war time
libraries, universities and transport systems saw massive amounts of
growth, and the need for writers to chronicle these processes
increased.

The discovery of the transistor in 1947 allowed cheaper production
of computers. Now individuals and small businesses could afford to
buy them. As a result, the need for writers who could explain and
document these devices grew.

The first known computational technical document was an
instruction manual for the BINAC computer written by Joseph D.
Chapline in 1949.

In 1953, two organizations were founded: the Society of Technical
Writers and the Association of Technical Writers and Editors. Today
they are known as S ociety for Technical Communication (STC).

12 Share this book:


1960s saw the growth of technology, particularly in the electronics,
aeronautics, and space industries. 1970s and 1980s were marked by
the expansion of the consumer electronics into people’s lives. These
were the decades when the demand for technical writers was
skyrocketing.

In 1976 the Modern Language Association (MLA) approved a panel
on technical writing at its annual conference. And in 1980 the U.S.
Department of Justice announced technical writing a profession.

In 1980s PCs arrived in the workplace, accompanied by large
manuals with names such as “Guide to Operation”.

Nowadays

In 2000s how-to books and guides increased in popularity. And in
2010s applications and programs included tooltips and product
tours, and web help became even more sophisticated.

Nowadays technical documentation is required in every field, from
construction to food processing and preservation. Software
documentation and user guides are considered a must for any
application or software. If you are particularly good at plain writing,
you have good research and exploration skills as well as other traits
of a good technical writer, you should definitely consider becoming
one.

13 Share this book:


The Purpose of Technical Writing

You may have seen this job title popping on professional platforms
or in your network, only to ask yourself: what exactly does a technical
writer do? The intuitive definition of technical writing is that it is a
profession that focuses on documenting the knowledge base of
products and services and making them easy to understand by the
end user.

Let’s break technical writing down a little and see what this job
entails.

The job of a technical writer is to create specialized content (for
example medical news, product details, software manuals, etc.) and
communicate it as efficiently as possible to a specific audience. Of
course, the information the writer provides must be accurate and
without any gaps or room for interpretation. The content must be
presented and edited in a user-friendly manner so that people that
have no tech knowledge can understand the information without
difficulties.

Some of the most common examples of technical writing include
user manuals, help guides, online courses, and so on. If you’ve ever
come across one, you may have noticed that they use a certain
writing style and formatting. Regardless, the purpose is always the
same: to inform and teach the target audience and make it easier for
them to find the information they need about the products or
services they are using.

As more and more user manuals are going online, another purpose
appears - technical documentation becomes a marketing tool. And,
as a result of this evolution, a documentation team can start bringing

14 Share this book:


more money to the company by just doing their job. That's
something!
Chapter 2. How to Become
a Technical Writer?
How Do I Become a Technical Writer?

Some people like to write creative content or poetries. Others like to
explain to people how products or software works.

If you are particularly talented when it comes to breaking down
complex processes into easy-to-understand articles, then technical
writing might be the right niche for you.

Technical writing refers to the process of creating the documentation
and online authoring for certain operations, systems or software.
There are a lot of companies out there looking for full-time content
creators that can develop user guides and knowledge base on
different subjects – and, we’re not talking just in the IT industry.

As a technical writer, you can work in almost any industry, from
construction to food processing and preservation. Or, you can
choose to be a freelancer and choose the clients you want to work
with. If you’re on the fence about breaking into technical writing, this
article will present everything you need to know about what it
implies.
What Skills Does a Technical Writer Need?

15 Share this book:


In all honesty, the skills you need depend on your niche. However,
there are a few basic skills you need to develop as a technical writer:

⎯ Strong writing and communication skills;
⎯ Technical experience that is specific to the role;
⎯ Industry knowledge and interest.

Don’t worry if you don’t have any technical writing experience. Sure,
you may lack in some technical know-how and industry knowledge,
but just as strong writing takes practice, so does building your
technical skills.

There are plenty of job listing platforms you can navigate to see what
companies are looking for in a technical writer, so be sure to check
that as well to be fully prepared.

To get a clearer understanding what it takes to be a good technical
writer, refer to this blog post - 11 Skills of a Good Technical Writer. If
you prefer formal training, you can always consider attending a
technical writing course.

Freelance vs. a 9-5 Job

It’s certainly an age old question. Is it better to work as a freelance
technical writer, or look for a steady job within a company? We can
only guess that an answer like “it depends on your work ethics and
style” isn’t very satisfying. So, here’s a list of pros and cons for each
scenario:

Freelance Technical Writer
Pros
+ Flexible work schedule;

16 Share this book:


+ You can choose the types of projects you want to work
on;
+ You are your own boss.

Cons
- Sporadic payment;
- No fixed income, which can be a bit difficult in the
beginning;
- Constantly on the look for clients until you build a steady
workload.

Technical Writing in a Company
Pros
+ Build a high-level expertise in a certain industry;
+ Work with skilled professionals which you can consult
whenever you are in doubt about how to create the
online authoring;
+ Enjoy numerous benefits, such as insurance, a fixed
schedule, and so on.

Cons
- A desk job can become monotonous;
- It’s exclusively desk-based work.

Who Needs Technical Writers

As we’ve mentioned already, IT companies aren’t the only ones
looking for good technical writers, though it’s fair to say this industry
is the one where you’ll most likely find open job positions.

Still, technical writing can become useful for a variety of businesses
or institutions. An educational organization, for example, may need

17 Share this book:


an expert writer to create the curriculum or develop manuals for
students.

But, if you choose to go on this path, then you need to remember to
do your homework beforehand. Research the market and determine
what companies want from their technical writers. Get involved in
different projects that are related to the industry you are interested
in and build your portfolio. Also, check out this blog post called
Technical Writer Career Path that explains what career opportunities
a tech writer has.

Just as with any creative work, becoming a technical writer is a long,
arduous path. Not only that you need to practice your writing skills,
but also ensure that you are up to date with changes in your
industry. However, the benefits are well worth it.

18 Share this book:


11 Skills of a Good Technical Writer

What makes a good technical writer? This profession only seems
easy and straightforward. There are many hidden rocks in being a
technical writer, and, as for being a good one - there’s even more.

As a company that has a lot of experience of working with technical
writers because we create software for technical documentation, we
decided to create this list.

If you are an employer looking for a new employee, you can use this
article as a checklist. If you are a tech writer, we hope to provide you
with ideas for growth.

All the rest - just enjoy reading and learning new things.

Writing skills

The first and foremost, technical writers are supposed to excel at
writing itself. The main criteria of good software documentation is
the clarity of text. This can be achieved only by someone who knows
how to write, how to put the most difficult ideas in simple words.

A good writer usually just knows these things, feels when to use this
or that construction, which words suit best, etc.

All this sounds like some kind of a talent a person either possesses
or not. But, in reality, it all comes down to hard work and practice.
Read quality texts more, analyze the word choice there, figure out
text structures - you will be well under way to improving your writing
skill. Or, you can also try attending training sessions on the subject.

Ability to Work with Technical Writing Tools

19 Share this book:


Technology keeps moving forward. Nowadays, everything is about
efficiency, teamwork, and being agile.

The number of companies using software for documentation
authoring is going through the roof. No wonder - technical writing
tools are designed specially for technical writing, they offer very
task-specific functionality alongside with just being a user-friendly
text editor.

How can a technical writing tool make the work of a tech
communicator easier? As a rule, such tools feature workflows
developed for tech writer teams, they support popular tech writing
formats like Word, PDF, CHM, etc., and, also, there’s this thing called
Single-Sourcing that is able to save a lot of time and effort for a
documentation team. As a reference, you can check out a list of
features offered by ClickHelp, a tool for online documentation
authoring.

A good tech writer needs to be aware of what’s offered on the
market. Ideally, they should try out a couple of tools to know how
things work and figure out what appeals to them personally.

Research and exploration skills

These skill may concern any technical writer, but, it, probably, affects
outsourcers the most.

Working in an outsourcing company means that you have to deal
with a variety of client companies you have never heard of and are
unaware of their products.

20 Share this book:


Writing software documentation under such circumstances is a
tough call. Only after hours of thorough research you can gather
enough information on the given field to start with the writing
process.

Besides, doing some research is always great even for the area you
feel pretty confident about. Remember, we live in the constantly
changing world. So, here’s to double-checking!

Being Systematic

Software documentation is a system. Some user guides can get so
big and complex and stuffed with help articles that it is hard to
believe that it is a system. Well, maybe, it isn’t anymore. And, that's
bad.

First of all, poorly structured documentation ruins user experience as
it fails to fulfill its main function - provide people with easily
attainable data.

Secondly, documentation writers suffer, as well. When there’s no
system it is really hard to maintain the user guide further.

So, a good technical writer is the one who always plans the
documentation structure in advance and never makes a mess hoping
to clean it up later.

Teamwork

A technical documentation team is part of a bigger mechanism. They
must be able to communicate well with other departments. Technical
writers need to talk to one another, editors, designers, developers.

21 Share this book:


At first, technical writing seems to be the work cut out for introverts,
but this appearance is deceitful. Don't forget about all the
conferences made by and for technical communicators!

The thing is - a user guide can only be clear and make sense when its
author knows how everything works. So, there’s always lot of
communication and inquiries about all sorts of things.

Being Good at Single-Sourcing

You can be using a tool for technical writers and never fully realise its
potential. Single-Sourcing is a time saver for any tech writer. If you
want to be able to get more things done without additional effort,
you should learn these techniques.

Basically, Single-Sourcing allows creating multiple documents using
one and the same source. For example, there’s a task to create pro
and beginner versions of a user guide. With Single-Sourcing, you can
create just one document, mark the parts meant for pros only and
get two different documents as outputs.

Another example would be the usage of variables in your
documentation project. You can create a variable (a kind of a
container for keeping some data) with the product version. This way,
later, you’ll be able to change the version in your documentation by
just changing the variable value once.

Sociology

Knowing the basics of sociology is quite a useful tech communicator
skill.

22 Share this book:


Technical documentation is created for users of some product or
service. Each product or service has its core user base and target
audience. One of the tasks of any tech writer is to figure out who the
end users are. As soon as this is done, the writing process can begin.

The easiest example is the difference between B2C and B2B user
guides. In the first case, the explanations must be really simple and
somewhat down to earth. While, in the second case, the content is
supposed to be deeper, more complex and detailed.

Sociology in terms of documentation authoring is knowing how the
readers think and figuring out the best way of delivering content for
this particular part of society.

Critical thinking

Critical thinking is a broad term. And, also, it seems to be one the
most needed skills for a tech writer.

Basically, critical thinking can be explained as the ability to make
reasoned and clear judgements.

This concept includes gathering information, analysing and
systematizing it. Just being systematic is only a small piece of the
whole critical thinking story.

What makes a good critical thinker? Well, most of theories on this
matter are saying that the answer is - personal experience. And, this
does make sense. The more conscious the whole process of getting
and processing information is, the clearer the output will be.

Web Design Basics

23 Share this book:


This skill is optional. But, recent years show that writing in Notepad is
not enough anymore. More and more online documentation tools
appear on the market. Some of them offer ready templates that you
can use as is or tweak them to your liking. And, the tweaking can also
be done using HTML and CSS.

Even if we look from the UX point of view - design can either improve
or ruin UX - bad-looking color schemes, ugly screenshots… Users
won't be satisfied with this, for sure.

Education

So, does a tech writer need a special diploma?

Yes and no.

Of course, it is somehow easier to become a technical writer than a
front-end developer without one. In most cases, you don't need a
degree for technical writing. But, still, many employers have certain
expectations. Here’s the list of the most appreciated bachelor
degrees for a technical writer:

● Journalism
● English
● Communications
● Computer science
● Engineering

Common Sense

Yet another ‘must have’ for a technical communicator. And, for any
human being for that matter.

24 Share this book:


Your common sense will help you see when you are doing the right
thing. Like, how many screenshots will be enough to explain this
topic on rocket science. If your common sense is telling you that no
screenshots are needed for rocket science, than I’ve got bad news for
you ;)

Reality checks help restore common sense greatly. Don't be too
self-assured too often - go ask around and listen to people’s
opinions.

Conclusion

The list of skills that can be useful for any technical writer is now
complete. This doesn’t mean, of course, that a technical writer has to
be all of these things, no. But, in tech writing, like in any other
professional field, there’s always an opportunity to grow as a
specialist.

If you are really interested in achieving a lot as a tech writer, check
out the blog post we have recently published on what a technical
writer career path can look like. We hope, that this info combined will
show you the direction towards improvement and success.

25 Share this book:


Technical Writer Career Path

Some writers dream of creating the next Harry Potter or Catcher in
the Rye. Some hope that their plays will be turned into the next Pulp
Fiction. And, others find joy in explaining how things work and
helping others to perform certain tasks and hope that one day they
will create software documentation for a big Fortune 500 company. If
that sounds like you, then you’re probably interested in a career as a
technical writer.

However, making it in this overly competitive industry requires a
particular set of skills and the desire to continuously learn.

Here’s what you need to know to become a technical writer.

Education and Background

Technical writers don’t necessarily come from the same background,
but range from English, journalism, and technical communication to
science or engineering. Of course, people with a technical
background will have an easier time understanding the topics they
have to work with, but you can always take a few courses to enhance
your knowledge.

You can take a technical writing course in colleges and develop the
skills you need to write software documentation. Consider also web
design and programming for a crash course on how software is
created and works.

And, of course, there are tricks and hacks that no college can teach.
You get to discover those with gaining some tech writing experience.
We did a blog post on one trick that can be helpful for a tech writer

26 Share this book:


of any professional level - improve technical writing with the 20/80
Rule.

Career Opportunities

Before deciding on a specific path, explore the possibilities this
industry offers. Learning different software and approaches will help
you become more versatile and experiment with different situations.
Then, you can specialize in one particular area of technical writing –
medical writing, software documentation, content management,
policies, finance, proposal writing, and more.

A typical documentation team will consist of authors, editors, a
manager, and others that need to work together to deliver
professional content and create a knowledge base.

Advancement Opportunities

Contrary to popular belief, technical writers don’t just write user
guides or manuals, but also contribute to the lifecycle of the product.

So in case you’re wondering about growth opportunities, you will find
plenty in this industry. Depending on the company you will be
working for, you could juggle between titles like “documentation
specialist” and “information developer” or other technical and
managerial tasks. Later on, you could head towards various positions
such as “information architect,” “publication manager,” “technical
editor” and so on. You also have a lot of areas to decide between,
such as content strategies, authoring tools, style guides, or review
and publish processes.

Whatever you decide, technical writing is a vast niche that offers
many career advancement possibilities. If you remain in this

27 Share this book:


technical communication area, you can always climb up the ladder of
management. For those that are considering switching, business
analysis is a very good and quite natural transition. Or, you could just
as easily find yourself working in usability and user experience,
creative writing, content strategy, content curation, and even product
design.

The technical writing niche has broadened greatly, offering a lot of
jobs and opportunities. Forget about the general opinion that you
will just sit at the computer by yourself – the profession is much
more collaborative and interesting than that.

28 Share this book:


5 Simple Steps to Build a Career in Technical Writing

So, you're considering a career in technical writing. Maybe we're a bit
biased, but that's an excellent choice. You'll get to work closely with
the products and services that may change people's lives and
prepare user documentation for manuals, articles, online help and
other supporting documents. It's a gratifying job, though not without
challenges.

Here are some of the challenges you will face:

● A big responsibility;
● Juggling between technical jargons and simple language. You
may find this related article useful: To Jargon or Not To
Jargon in Technical Writing;
● At times, it may seem monotonous.

But, the benefits outweigh the disadvantages:

● Developing expertise in a certain industry;
● Working on interesting projects;
● Staying up to date with the latest technological trends.

There are a lot of companies out there looking for skilled technical
writers to help them create their knowledge base – and, we're not
referring just to the IT industry.

Here's a list of five things that can help set yourself apart...

Practice

29 Share this book:


Technical writing is, at its core, dependent on good writing skills.
Now, you can't exactly learn how to write well, but with a decent
amount of practice, your skills can improve significantly.

Once you get the hang of things, you should consider publishing your
work. Start a blog dedicated to tutorials in the industry you want to
work in, and slowly build a following. It's a great form of practice and
something you can use to your advantage at an interview.

You may also like to read about the 11 essential skills of a good
technical writer.

Consider Open-Source Projects

Just because you're not in the industry yet, doesn't mean you can't
acquire experience working in it. Open-source projects are in high
need of user documentation. Look for something that is relevant to
your skills and contribute to it.

Stay in the Loop

A job in technical writing requires a lot of research. You're not all
knowledgeable, and you need to study a lot to be able to
communicate the desired message to the target audience. But, if you
want to set yourself apart, then you should go the extra mile and try
to keep up to date with the latest trends in your niche. That way, you
can become an expert and have an easier time acquiring projects.

Get Certification

Although not mandatory, a diploma in the industry you're interested
in or even certification in writing or communication can give you a
great competitive advantage. There are a lot of classes you can take

30 Share this book:


online that can help you practice your skills and acquire more
knowledge.

Differentiate Yourself from Other Technical Writers

Technical writing can be a pretty competitive industry, so you need to
show employers that you can do more than just write quality
content. For instance, if you want to work in a software company,
you could also learn to code. That way, you'll be able to understand
the service better and create a fantastic knowledge base. You should
also become knowledgeable in using help authoring tools to gain an
advantage over other writers.

Over to You

Regardless if you opt to work as a freelancer, or you decide to join a
company full time, use these tips to build your portfolio before you
start sending your resume.

31 Share this book:


Technical Writer Job Challenges

Technical writing doesn’t come without its fair share of challenges.
For an outsider, creating user documentation may seem like a
straightforward job: you receive the project details, analyze the task,
and then just start writing.

But is it that simple?

A technical writer is, essentially, a communicator, and their job is to
transfer information from one party to the next. They conduct
research and create various forms of content, such as text,
audio-visual, and multimedia that the company will integrate into
manuals, design specifications, or the help section of their website.

Anyone who’s ever attempted to create content targeted at a broad
audience can tell you that it takes a lot of craft to write something
that is both engaging and delivers the desired message. Factor in a
couple of t echnical jargons and the job just got harder.

So, what are the challenges that a technical writer faces?

Let’s find out!

Making It Simple versus Being Specific

That is perhaps the biggest dilemma technical writers face when
creating user documentation: should they use simple language that
can be understood by more people, or do they employ technical
jargon for accuracy but risk user comprehension.

32 Share this book:


Keeping a healthy balance between the two can be difficult. Making
the content too simple can show lack of expertise and users might
distrust you, but too much technical jargon can be hard to
understand for those who are not accustomed to it. It’s why technical
writers also need to know the type of audience the content will be
targeting.

Knowing Where to Get Data

Being a technical writer doesn’t mean that you know how everything
works. Most of the time, they spend a lot of time looking for
information and trying to understand the topic before writing.

But then again, you can’t exactly just Google it. Expert technical
writers know where to look for the information they need and have
access to a vast database of specialized articles and studies. They
also use help authoring tools (HATs) to assist them in the process of
creating and managing the online help systems.

BTW, a HAT is not necessarily some software. What else can it be?
Check out this article on the top 7 help authoring tools for tech
writers t o find out.

Knowing What Needs to Be Said, and How

Technical writers must work with other departments, such as the
developers, and ask them to explain how the product works.
Developers can provide the writers with extensive data about the
project, but it is up to the technical writer to decide what needs to go
in the documentation, and how it should be presented.

They’re an Essential Part of the Team

33 Share this book:


Developers often think they can write the software documentation
themselves. The problem is that they can’t put themselves in the
audience’s shoes and don’t understand how the user relates to the
product.

Programmers start from the core and build outward when
developing, but users might be confused by this way of thinking.

It’s why documentation is best left in the hands of a technical writer.
Sure, it doesn’t come without its challenges, but the results can be

greatly rewarding.

34 Share this book:


Chapter 3. Tools & Tips

Free Tools for Technical Writers: Video & Image
Editing

Technical writing is a very broad term, it is much more that just
'writing' stuff. It often involves design, graphics creation, video
authoring, community building, and more. And the good news is that
most of these tasks can be solved with free tools and services. In this
chapter, you will learn more about such tools, and how they can help
you do your job.

Here is what we are going to talk about:

● Video & Image Editing
● Community & Social Networking
● Statistics & Analytics
● Free Graphics
● Other free tools

So, let's get started by taking a look at some free video and image
editing tools.

FastStone Image Viewer

FastStone Image Viewer is a tool for image viewing, converting and
editing images. Above all, FSImageViewer is freeware for Windows
that allows effective picture browsing. And, by effective, we mean
fast and convenient. The UI is very intuitive, Windows Explorer-like.
The program does a great job displaying all the pictures fast, even

35 Share this book:


when you have some big files (in the RAW format, for example), the
delay will be minimal.

The range of supported formats is also a strong point. All major
graphic formats are on the list: GIF, PNG, TGA, BMP, JPEG, JPEG 2000,
PCX, TIFF, WMF, ICO, etc.

But, why is this tool so interesting in terms of documentation
authoring? If you look at this freeware a bit closer, you'll be able to
see its great editing potential. Besides providing users with
numerous brushes and filters, this lightweight tool can do a lot:

● crop, resize, rotate pictures
● adjust color, levels, curves, etc.
● apply image color effects and other special effects (drop
shadow, framing, annotation, etc.)
● draw lines, texts, geometric shapes and callout objects
● manage images (including the possibility of creating tags)

36 Share this book:


● etc.

FSImageViewer can cover all basic tasks as far as screenshots and
other images in documentation are concerned. Of course, it is not as
functional as Adobe Photoshop or other super multi-functional
editing products, but, being a free tool, it still can make the famous
Adobe software a bit nervous.

Even more pros here: there's a portable version of the tool that can
be run from a removable storage device.

Now, to the cons.

Though, the number of supported formats is quite impressive for a
free tool, sadly, you can not convert images to some of them.

The truth is you won't be amazed by the product design either, but
that can only mean that the developers put much more thought and
effort into the functionality, than the tool’s look and feel. It is not
critical, of course, as long as all the needed functions are at hand,
but, still, FastStone Image Viewer is failing to live up to what's
expected by the modern audience.

In conclusion, we can say that FastStone Image Viewer is a
high-quality tool with a great potential to become your favourite
image editor. It has vast functionality to cover the needs of a
technical documentation writer, it is easy to use and fast. Besides,
the tool is regularly updated. So, if you decide to get picky - just
remember that this is a free tool after all.

LICEcap

37 Share this book:


LICEcap is a freeware program for creating GIF animations by
capturing some area of your screen. There are Windows and Mac
versions of this tool.

GIF files are often used by technical writers as this format offers an
easy way of demonstrating something quickly. And, talking about
online documentation, GIFs are supported by any modern browser.

If you have been looking for an extremely simple tool to quickly
produce some GIFs - I've just found one. Here’s what this freeware
does:

● recording captures directly to GIF or LCF (its own format
allowing higher quality that can be opened with third-party
software, i.e. REAPER)
● moving the recording area around the screen
● pausing and restarting recording
● inserting a text frame with customizable duration
● adjusting frame rate
● recording mouse clicks
● etc.

As you can see, LICEcap can come in handy for technical
documentation - you can use it for creating short demonstrations or
to add visuality to your help topics and tutorials. The recording goes
like this: you launch the program, resize the recording window, set
max FPS, and click 'Record'.

38 Share this book:


After the recording process is started, you can move the window
across the screen, but it won’t let you resize anymore.

If you click ‘Pause’, a new option will become available - text frame
insertion.

39 Share this book:


The most obvious drawback of this freeware tool is - it can’t do
editing. So, if you need more than just a quick screen capture,
unfortunately, you’ll have to look elsewhere. Plus, LICEcap won’t
allow capturing a full desktop, which is bad news also.

And, you shouldn’t be expecting too high a quality from the resulting
GIF files - they are at 256 colors max. What you should expect though
is overlarge resulting files regardless of their size or length.

To sum this review up, LICEcap can’t do much in terms of editing (to
be more specific - it can do nothing at all), but it is serving its main
purpose well, which is providing a super fast and easy way of
creating GIF animations recording your desktop.

Advanced Image Editing - GIMP

You all, probably, know this one. GIMP is a freeware tool for
Windows, OS X and Linux, that dares competing with Photoshop, and
we mean it! What started out as a school project back in 1995
according to Wikipedia, has grown into a complex and powerful
open-source graphics editor considered by many the best free tool of
the kind out there. This tool supports all popular formats, and it is
updated on a regular basis.

Indeed, GIMP is complex and multifunctional (mostly, because it is
extremely plugin- and extension-friendly), so we won’t go into too
much detail in our review. Let’s concentrate on what it can bring to
the tech writer’s table.

Well, surely, this tool possesses all the necessary functionality for
screenshot/image editing. Resizing, cropping, adding text, drawing
lines and additional elements... But, using it only for these basic
things would be a waste of functionality. With the GIMP toolset, you

40 Share this book:


can work on customizing your documentation design to increase
your user manual's usability, make it more visually attractive and
unique.

But, its greatest weakness arises from its very strength - to master
this tool is not that easy. The user interface kind of reminds us of
Adobe PS in a way, but when you look closer or try actually doing
something more or less complicated in GIMP, you’ll realise that you’ll
have to learn first. On the bright side, there are many user forums,
tutorials and trainings that can help.

Another thing is that, although plug-ins are truly numerous, they
need to be downloaded from all over the Internet.

All in all, GIMP is a one-of-a-kind offer - tons of functionality for free.
It is a stable tool of high quality, and if you are not scared of learning
something new, you should give GIMP a try. It can help you perform
image editing tasks of any difficulty. As we always say - technical
documentation must be beautiful!

41 Share this book:


Free Tools: Community & Social Networking

Disqus - Commenting Service

We are going to start with Disqus, an online commenting service that
got very popular and being used in various online resources - from
blogs to software documentation. This popular free service can be
added to websites or communities allowing people to leave
feedback, discuss the material, and even get assistance from others.
Wikipedia states that around 75% of websites, who used a third-party
commenting or discussion system, chose Disqus in 2011.

The idea is very simple - you create a Disqus account, and then it will
give you ready HTML markup to insert to your web pages. Once you
do this, your pages get a commenting area at the bottom. It supports
comments moderation and management, so you are notified when a
new comment is added to your page, you can delete the comments if
required.

No logging in is obligatory if someone just wants to leave a comment
- guest comments are supported. But, this way, the user would miss
one of the most interesting Disqus features - keeping history of all of
the comments in one place. When users authenticate in Disqus when
leaving comments, they get a Disqus profile and can see all the
comments they ever left in online resources that use Disqus.

42 Share this book:


Since user manuals are also online resources, using such
commenting services makes total sense - you give your users a way
to leave their feedback right in the context of the topic they are
reading. This way, you can both assist them easier by answering their
question and also improve the topic in the future to cover that
question. With this idea in mind, we have built Disqus support in our
own software documentation tool.

We have also realized that Disqus can be used as a collaboration
platform - giving the documentation writers a way to discuss things
before they are published to the end users. We described this usage
scenario in this blog post: User Comments in Online Documentation.
What is really great about this tool is that, basically, it allows you to
build a community for free. And, we consider an online
documentation portal a great platform for building a user
community.

Being a free tool, Disqus makes money from ads. And, its Privacy
Policy warns that some non-personally identifiable information can
be disclosed for whatever reason to any third-party and also used for

43 Share this book:


ad targeting. This is expected and from our experience their ads are
not disturbing, so that’s fine.

To sum this up, Disqus is a huge and very popular commenting
system. It allows you to easily start building a community of real
people around your content. This tool is fast to implement and easy
to use.

AddThis - Social Tools

AddThis gives you a quick way to add sharing buttons to any online
resource - your website, online user manuals, FAQ pages, etc.

In general, sharing buttons is good stuff. When people share your
content through social networks, this brings more traffic and can give
additional exposure to your company. It is a form of free advertising,
you just need to create some great content first.

If you have some truly unique and interesting content that you
believe people might want to share with others - you need to give
them this opportunity. And, it better be convenient and easy. When
there are no sharing buttons within reach, people won’t do anything.
We are getting lazy, and "copy/paste" is no longer an option. Living in
the hi-tech world with marketing and UX playing the leading role has
changed our habits - we expect the right things to appear at the right
time in the right place. So, AddThis and such-like services would be of
great help.

This is an example of how AddThis buttons look on our website:

44 Share this book:


AddThis has quite a lot of positive feedback from those who use it.
The tool also integrates with Google Analytics.

SurveyMonkey

SurveyMonkey is a great service for collecting feedback. This tool is
used for creating surveys and analysing the results later.

Surveys can be used for both: interaction inside your team (Where
do we go next Friday folks?) and getting feedback from customers
(Which feature of our product do you like most?).

It goes without saying that the free basic plan has some restriction.
But it will still work for a pretty big team (and, from our experience,
documentation teams are usually rather small). For example, as of
the current date, you can create a survey with up to 10 questions and
get a hundred answers for it without spending a dollar. This works
like magic if you need to quickly get what people think about some
changes in documentation, changes in the workflow, whether they
are digging the new color scheme... pretty much anything.

45 Share this book:


You can easily create a survey and add a link to your user manuals to
receive feedback. Register on the SurveyMonkey website, then click
the Create Survey button on the home page as shown below:

Get creative (or go simple) with the survey Builder. After you’re done
with the questions, click Next:

You’ll find yourself on a page with a customizable link for your newly
created survey. It’ll look somewhat like this:

46 Share this book:


Insert this link in your help topic or your web site and voila!

The best thing about Survey Monkey - you don’t need to have any
special skills to be able to work with it. The resulting survey layout is
very clean and simple:

47 Share this book:


Even though the free version has some restrictions, we would
recommend this tool. It is a "must have" for doing a quick research.

Summary

We have reviewed some high-quality free tools you can use to
promote your company and get benefits from user feedback. If used
wisely, all the tools we talked about above can do a lot of good. Give
them a try in your software manuals and let us know what you think!

48 Share this book:


Free Tools for Technical Writers: Statistics &

Analytics

Analyzing statistical data and coming to right conclusions can
become your guiding light on the road to success, can help you see
the right direction for further development. Well, all of this is
achievable only with the right tools. In this blog post we’ll try to find
out what free services can offer to us. Let me jump ahead of myself
and tell you - tons of useful statistics can be done for free, so we will
also try to understand how to use all this data to get maximum
benefit.

Google Analytics

Google Analytics is immense. Just think about it. As Wikipedia puts it -
almost 50% of top million websites are using it. I doubt we even need
an introduction for this review, but, for all Marty McFly’s out there,
here it is: Google Analytics is a free statistics service launched by
Google in 2005 to track web traffic. You can get statistics for both
desktop and mobile traffic here.

To say the truth, it is not entirely free - it is freemium. Google does
offer a lot to enterprise. But, even if you stay with the free version,
somehow, you won’t really get the feeling that you are using an
incomplete product with limited functionality. Before even
considering buying a GA license, you need to make sure that you
have enough human resources. Otherwise, you’ll end up using the
same basic features that are offered for free, only you will be paying
a lot. You can spend a whole day trying to do some deep analysis on
the Google Analytics page, and you’ll merely scratch the surface.

49 Share this book:


A wide range of goals can be achieved with the GA tools. From simple
page view count to complex eCommerce research.

To make sure you don’t get overwhelmed with all the features, you
can finish Google’s online courses, get support or watch educational
videos on YouTube - all free.

We are using Google Analytics for both our ClickHelp Documentation
and the website. We’d like to share our all time favorite GA
functionality with you.

Our own history of working with this Google service shows that
Google Analytics is not only for websites - it can help making online
documentation a better user experience. There are many resources
that talk about using GA for websites, so let us focus on some ideas
that apply to online documentation:

● Audience | Demographics - say hello to your average client. The
entire Audience section is the first thing you need to explore and
think over. Here you get a clear idea of who your target audience

50 Share this book:


is. Try to generalize your observations, mentally draw a portrait of
your client. What are their interests? Age? Country? To realise how
to develop your product further, your target audience is the main
thing that needs to be taken into account.
● Audience | Mobile | Overview - knowing what devices people
use to view your documentation can help you get your screenshot
sizes right. Take a closer look at screen resolutions of the devices
used the most and resize images in your user manuals
accordingly. Also, make sure you don’t have any small elements -
they can be hard to click on a mobile screen - if you’re getting a lot
of mobile traffic.
● Behaviour | Site Content | All Pages - learning what help topics
are viewed more often than others can show you what product
features require special attention from users. This can mean that
the functionality needs to be improved (if we are talking about
software documentation) because users need some additional
explanation in this regard. Also, for your documentation team,
these popular topics should become a number one priority. This is
a good practice to update such topics first and make them more
comprehensible (e.g. by adding screenshots, videos, examples,
etc.)
● Acquisition | All Traffic | Referrals - this page can also help you
track where people come from. When you use context sensitive
help in your online tool, this section can show you which screens
generate the most clicks. Most probably, those screens are hard to
understand and users often need assistance. This should be a
signal to your software developers and UX designer - they need to
do something with those screens to help the users.

By looking at your online help stats in GA, you can make you own
conclusions and some of them may be pretty unexpected. Let’s also
cover some of the ideas how you can use Google Analytics for you

51 Share this book:


website.You will see how the same GA pages can be interpreted
differently depending on your goals:

● Acquisition | All Traffic | Channels - here you can analyse how
people get on your website. Keep in mind that your Social and
Organic Traffics are the two things that will boost your online
presence and drive your business in the long term.
● Behaviour | Site Content | All Pages - tracking page views is a
great way to understanding how changes on your website affect
traffic. For example, if Bounce Rate on some particular page goes
down while the number of visitors increases - congratulations! You
have done something right. Now, you need to figure out what it
was, but this is a different store.
● Acquisition | All Traffic | Referrals - this page displays how
many people come to your website by clicking links on other sites.
Going through these metrics will give you an idea of how good
your current marketing strategy is (ads, guest blogs, etc.)
● Behavior | In-Page Analytics - the last but not the least. With this
functionality, you can find out how changes of your web pages UI
change the user behaviour on that page. Knowing how often
specific links and buttons are clicked can help you choose the right
page layout, wording, color scheme, etc.

The more you use Google Analytics, the clearer you understand what
works and what doesn’t. Gaining more experience in this field will
help you learn a lot about your audience, the market you are in, what
is expected of your company and much more. Google Analytics is a
service that we would highly recommend for any company,
regardless of its size and structure, for analyzing online
documentation and websites.

Webmaster Tools

52 Share this book:


Webmaster Tools is a great addition to Google Analytics (GA) that
deals mostly with SEO. Working together, these services can make
your life much easier. While GA can scare people off with its copious
functionality, Webmaster Tools is simpler and easier to handle.

The main idea behind Webmaster Tools is websites indexing. You
need to submit your sitemap here to ensure your site is indexed
properly.

Once the website is indexed, you can sit back, relax, and reap the
benefits - that is, increased visibility on the web and improved views
count. Next time you’ll need to worry about indexing is when your
website gets updated. Webmaster tools can help index the updated
pages, so they will be visible in search engines as soon as possible.

This free tool is used to fine tune the indexing process, as well. For
example, you can exclude some pages from the search using the
robots.txt file (What is robots.txt?), and then use Webmaster Tools to
make sure you did it right.

Webmaster Tools is great for analysing the search keywords people
use in Google when they get to your website or online help. Looking
through keywords can help you see what people were looking for
and expecting to find. You might even reconsider your keyword
strategy: paraphrase or delete unused keywords, add new ones that
are gaining popularity.

All in all this service is a good choice to boost your SEO efforts and
make your website more visible.

Summary

53 Share this book:


As you can see, there are free tools that can help you gather the
statistical data and make sure your online content appears in the
search engines. Software documentation is a great SEO asset and
you need to make sure your clients can easily find it on the web.
6 Tips For Online Documentation Design

When you need to create user documentation, one thing you start
thinking about is how this documentation will look like. Apparently,
you can write great content and describe all the features for users.
But what about the style, layout, fonts, colors, background, etc.? Even
if you think that developing some special design for user manuals is
too much, you still can't just plaintext it. Online documentation has
to look nice!

As far as the documentation design is concerned, some ground rules
are to be set:

● your help topics must be readable;
● all additional elements (warning boxes, list bullets, tables, etc.)
should be informative and definitely not distractive;
● the design should be responsive and look good on mobile
devices;
● colors of choice should match,
● etc.

Having a quality user manual can do you a lot of good: gain several
authority points from the customers, ease the pressure on your
Support team, increase brand awareness through matching
corporate design. Besides, quite often, online help is the first place
an angry user goes to when they experience some issues, so your
task is to make them feel welcome!

54 Share this book:


Not so long ago, our team faced the task of creating several design
templates for online documentation. Going through this process
gave us a lot of experience that we are willing to share with you in
this blog post. So, here are the six tips for creating an online user
manual design.

Target Specific Audience

Before even starting working on your documentation design, you
should sit back and think a couple of vital things over, namely - who
are you doing the design for?

When you determine specific demands your users might have, you
can start making your customers happy.

For example, we created a whole design aiming at a certain part of
our target audience - people working with API documentation:

55 Share this book:


Example - API Documentation Template in ClickHelp

This template was designed to visibly separate code from text with
the help of blocks with different backgrounds.The catch behind this
kind of design was that we had to think through each element so that
they matched the dark and the light backgrounds. We approached
this from two sides: we did some elements in two color schemes, and
other elements were simply designed to match both backgrounds.

56 Share this book:


Example - Table Styles for Light and Dark Backgrounds

Example - Information and Warning Box Style for Light and Dark
Backgrounds

Follow The Trends

Being too unique a snowflake when designing things can get you into
trouble. But, I'm not encouraging you to follow in somebody's
footsteps precisely. This is just the matter of what looks edgy and
sharp today, and what doesn't.

57 Share this book:


Example - … and what doesn't

Well, HTML Help Workshop has an excuse - it is no longer developed
for a long time. Just make sure your documentation does not look as
if your product is no longer developed as well.

The second thing you should do is research. There are always some
giant companies that set the trends for many things, and web design
is not an exception. The rise of the mobile Internet made all the A-list
players turn to simple and clear-cut shapes that would be convenient
for their mobile users. So, now, tiles which became popular thanks to
Metro design (renamed to "Microsoft design language" later) are
trending.

We used tiles in a couple of our documentation designs. For
example, our Colorize template looks good on mobile, as well as on
big screens with its tiles and matching bright material design colors.
Material design is one of modern design trends started by Google

58 Share this book:


and it's not about colors alone - they have the entire
material.google.com domain dedicated to it.

Example - Tiles Layout for Help Topics

Do Not Overcomplicate
Lightweight designs are here to stay. Mobile traffic is still on the rise,
so, no heavy, highly-detailed design elements. Some people call this
trend C
omplexion Reduction.

When I knew I had to create a simple and minimalistic design, I
thought to myself: well, this is just a perfect task for me, a lazy
designer. Gimme 10 minutes, and the new template is here!

59 Share this book:


Well, nuh-uh.

Turns out, the simpler the shapes are, the fewer colors you use - the
more difficult it is to make it look like anything but a
Windows-95-is-back disaster. Be thorough - study the form, study
how colors match, how far the shadows must go, and whether you
need shadows at all.

With that in mind, we worked real hard, re-did things a few times and
finally managed to create a minimalistic, functional and good-looking
documentation template:

Example - Minimalistic User Guide Template

Responsive Is The New Sexy

You have probably noticed how everyone seems to use high res
images and videos on their websites. I'm talking mostly about the
landing pages now, the ones that are here to impress you. Why not
impress and inspire people with documentation? Or, coming back to
Earth, what should one do about a dozen of screenshots on a single
page? How long will that take to load them? Be always concerned
about the load speed, screen resizing and mobile users.

60 Share this book:


Responsive design is no picnic. To make this process as painless as
possible, try reading this article: Responsive HTML. Part 1 - Screen
and Mobile Emulation. If you need to make your content look good
on mobile devices and don't know where to start, the article is for
you. You will find a step-by-step tutorial on making your HTML
content responsive in there.

We included a pretty large picture as a signature element for one of
our templates. The rest of the design was made to blend in smoothly
color-wise and style-wise.

61 Share this book:


Apparently, the example above is based on the assumption that the
image is just a background thing, not a screenshot. You should not
hide screenshots even in the mobile view of your online help topics.
Instead, the screenshots should resize to fit the screen width and
avoid layout issues. When creating user manuals in ClickHelp, this is
taken care of automatically by ClickHelp itself - large screenshots will
auto-resize to fit the width of the browser window properly.

Awesome Fonts And Where To Find Them

62 Share this book:


Web design trends are about fonts, as well. The most prominent
change that we've all noticed recently - sans serif is everywhere.
There's an opinion, however, that serif is not long gone, and it will
strike back. Let's wait and see, and still use sans serif for now...

The ultimate source of all the awesome fonts you saw a million times
but never learned their names is, of course, the Google Fonts service.
Google's font collection is impressive, and the service is free.

There is something a fellow web designer once told me - never use
fonts that your don't know. The rule of thumb is to use popular fonts
as they are usually popular for a reason: they would not look clumsy
and awkward and would be easier to percept in general. Also, people
like seeing familiar things - this is not only about brands, this is about
fonts as well.

We are using a big deal of popular fonts from Google Fonts in our
templates, and we are pretty happy about that. We have also learned
a couple of typography tricks from Google in their Style Guide.

Here's an example of a design we've created, perfectly readable and
clear:

63 Share this book:


Example - Coffee Break User Manual Template in ClickHelp

Talking about popular fonts... I have to make a comic sans joke now, I
apologize for that. Just one tiny old joke. Comic Sans walks into a bar
and the barman says, “We don't serve your type here” :)

The Beauty and the Speed

Responsive design is not a cakewalk, of course. There are though a
couple of tricks that can help you create a good-looking fast-loading
design and save you some time - patterns!

Instead of having one huge image you can have a tiny one, repeated.
We advise you check out free resources like this one -
https://www.toptal.com/designers/subtlepatterns/.

If you are not completely satisfied by what's being offered, you can
take a pattern and modify it in accordance to your needs. The
awesome subtle space banner at the top of the page is made from a
pattern.

64 Share this book:


Example - Using Patterns for Backgrounds

Online Help Design Tips

When you need to create online documentation template for your
user manuals, our tips would be:

● Target specific audience
● Follow the trends
● Do not overcomplicate
● Ensure responsiveness
● Choose the right fonts
● Balance between beauty and the speed

We hope that our tips will help you create a perfect online help
design. And, remember - you are better than Times New Roman!

65 Share this book:


3 Ways To Create Documentation Color Scheme

As much as we would like not to trouble ourselves with inventing a
documentation design – there’s no avoiding it. Your documentation
is what represents you to your users, so it better look decent.

You do not necessarily need a designer to fulfil this particular task. In
this post, we are going to show you several approaches to creating a
color scheme.

Use A Template

One does not simply write user manuals in Notepad. If only it was
that simple. So, probably, you are already using a tool for
documentation authoring. If not, then you should most definitely
consider doing so because documentation is so much more than
plain text: screenshots, schemes, tables, ordered lists, and maybe
even more professional things, like single-sourcing, access
restriction, a blood sacrifice for gods that will help you get your app
version right when a new one comes out, and you suddenly need to
change that one number on each and every page (ah, here’s to living
in the XXI century! In documentation authoring tools like ClickHelp,
you can just use variables to store the version number, so you won’t
have to pixelhunt it throughout your whole documentation), etc.

Documentation authoring tools can help you out in many aspects of
your working process, design included. Pre-configured templates are
almost always part of the deal.

As a rule, software for documentation writing features several
templates that are designed for different kinds of documentation.

66 Share this book:


For example, here’s a template for API docs with light and dark
blocks:

So, you will have some options to choose from.

Of course, using a ready template will save you a lot of time, but
don’t forget that it should still be relatable to your business. Here’s
an approach to consider – pick a ready template that matches your
company style the most and do some minor repairs.

Pros
+ You get a ready design
+ Designs are created by professionals

Cons
⎯ Templates are not always free
⎯ Ready designs will not always fit in terms of your corporate
style
⎯ Some changes and fixes are still needed quite often

Go Corporate

This approach requires a bit more head scratching. Each company
has some basic design solutions that are used in their product
design, on their website, in their ads, etc. Your style is what makes
your product stand out, this is how people will remember your brand
and find it among others. Even when users come to read your
manuals, they should be aware of what brand it is. Firstly, this gives
more visibility, a higher chance to be recognized in the future.
Secondly, this is still a huge timesaver. Thirdly, this will simply make
you look good – users will notice that people in this company are
really taking their job seriously, not leaving the smallest detail
unnoticed.

67 Share this book:


So, yes, using your corporate style for user documentation is a highly
advisable approach.

If there’s a style guide – this is just great. All fonts and colors have
already been decided upon. But, also, be ready to alter a couple of
colors and add some extra ones to the scheme. Like some
red-yellow-orange alarm-ish shades for warnings, for example.
Further in this article, we will give you some guidelines on color
matching techniques, so you’ll be fully-equipped to pick the right
additional colors based on your corporate style guide.

Pros
+ It will save you a lot of time as you don’t need to do the design
from scratch
+ In most cases, there’s a ready style guide at hand

Cons
⎯ There will most likely be some elements not covered by your
style guide
⎯ Some additional reworking will be required

Creating Color Schemes From Scratch

This is it – this is how complicated it gets. Creating a color scheme
anew. There may be various reasons why you are facing this task, we
are not going to dwell on this. Instead, we are going to offer you
universal steps for creating a color scheme. They can be used for
documentation portals, websites, standalone documents, etc.:

● Think of what your product stands for. Each niche has its own
peculiarities, standards and trends. Entertainment color

68 Share this book:


schemes gravitate towards brighter, bolder colors with more
accents while corporate style is more cold, neutral and plain.
● Choose primary colors. This will be the bases of the whole color
scheme. And, remember that you need only one/two primary
colors per design. See how to find matching colors in the next
section of this article.
● Choose colors for accents. Make sure you have some basic
colors and brighter accents, so your color scheme doesn’t look
dull, and all the important things are emphasized.
● Define what additional elements you will have (tables,
information boxes, warning boxes, etc.) and pick colors for
them, as well. As a rule, these are brighter, darker or more
saturated versions of the colors you’ve already picked for your
palette. If you are feeling like things are getting out of control
with this amount of hues – just go with your accent colors.
● Aaand it’s done! Take your colors, shake them up, do not stir.

Pros
+ The design will be truly unique
+ The whole process is under control from the start to the finish
line

Cons
⎯ Some research needs to be carried out if you are new to this
⎯ Developing a branding new design requires a considered
amount of time allocated

Color Theory Basics – Color Wheel

Now, to the most interesting part – let’s learn how to combine and
match colors. This is going to be much easier than you’ve probably
imagined.

69 Share this book:


The magic thing that will do almost all the job for us is called the
color wheel:

And, here are some ways the colors can combine with the help of the
color wheel:

The opposite colors are called complementary meaning that they fit
together well, but they also create a striking contrast. Use them in
limited amounts for emphasis.

Colors located next to each other are called analogous. They usually
create rather harmonious and calm color palettes. Think of a
complementary color to make your color scheme more vibrant.

70 Share this book:


Three colors evenly distant from one another comprise triadic color
schemes. Such color combinations are very vivid and bright. Try
using paler hues or make one color dominant while the other two
will serve as accents.

Free Color Scheme Resources

If for some reason you are still not feeling confident about your color
schemes after trying the above-mentioned tricks with the color wheel
– luckily, we have the Internet on our hands. And, it is full of great
resources for color scheme creation. Below, you will find a quick
overview of three great online resources for color palette creation:

paletton.com

71 Share this book:


This awesome resource gives you an interactive color wheel to play
with. You can use the techniques we’ve mentioned in the previous
section or try something new, like, for example, a tetrad combination
of four colors. This website can even create a quick example page for
your color scheme.

www.degraeve.com

This website offers a peculiar collection of generators, the color
palette generator is one of them.

72 Share this book:


You simply upload an image the color combination of which you find
visually appealing, and the app breaks it down into separate colors,
so you get a ready color scheme as an output.

Coolors.co

This website can generate random color schemes that you can
finetune later. Also, it stores an impressive number of ready color
palettes from other users. Feel free to filter them to look at the best
offers.

In this article, you got acquainted with three paths you can follow to
create a documentation design of your own: using a ready template,
creating your design based on your corporate style, or doing
everything from scratch. Whatever path you take, keep in mind the
color tricks you’ve learned in this article, they can turn out very
helpful.

There’s, actually, one more piece of advice for you – look around. Our
whole universe is here to inspire you, just look closer.

73 Share this book:


SlideShare Presentations in User Manuals

Many companies use SlideShare as a stage for their marketing
activities and specifically the content marketing. However, people
also host technical content there and you can do the same.

Of course, you would need to present your content in a form that
differs from what technical writers normally use - a presentation. But
if you give this a thought, you will realize that a set of slides is the
same module-based approach you use with topic-based authoring.
Also, using graphics is often a good way to explain complex things
simpler.

As Albert Einstein said, “If you can't explain it simply, you don't
understand it well enough.” And this is what you can try to do with
your technical content - put it in a simple form for your audience to
consume.

SlideShare is one of the most popular online presentation services
nowadays. It is easy to use to create an online presentation, and it is
easy to reuse that presentation elsewhere.

Embedding a Presentation in a Help Topic

Once you create a presentation in SlideShare, it goes online and
becomes available to your audience. And if it is a good one with
some useful content, you may really want to have it inside your
online documentation as well.

You could certainly just link to the presentation… Right, but this
would mean that your reader would have to leave your
documentation portal to watch the presentation. This would require

74 Share this book:


additional actions, and would not impress the readers - people don’t
like doing extra actions.

So, we will display our presentation inside a help topic, as an
additional way to explain some concept. To learn how to do this, we
will open our presentation on the SlideShare web site first and click
the Embed button below the slide.

Once we click the button, we will see a dialog with the embedding
options. We will use the HTML code in the Embed box. Note that you
can change the size of the presentation frame and the starting slide.

75 Share this book:


Just copy the embed code to the Clipboard and proceed to your
documentation portal. Open the target topic for editing and prepare
the place where you will put the presentation. We will just write
some placeholder as demonstrated below.

Now we will switch to the HTML Source view (click the Source tab at
the bottom of the topic editor) and locate the placeholder text.

And then replace this placeholder text with the embed code in your
clipboard.

76 Share this book:


Alright, we are done actually, and ready to check what this SlideShare
presentation looks like in the WYSIWYG editor of ClickHelp.

Now, when readers comes to your online documentation portal and
open this topic, they will see your presentation right away.

77 Share this book:


As you can see, it is simple to reuse your SlideShare presentations in
your ClickHelp documentation portal. Thanks to the HTML Source
mode, you can copy & paste the embed code in minutes. Hopefully,
this information was useful!

78 Share this book:


Chapter 4. You Are Hired.

What’s next?
How To Optimize Documentation Team Workflow

Your documentation team is one busy department. Useful
documentation heavily relies on your team’s ability to keep the
workflow moving, but in a business where things are notoriously
fast-paced, that can be a difficult thing to achieve.

With that said, you might find another article interesting, that is -
Documentation Team: How to Delegate Tasks. This might speed up
the processes inside your team, as well as what we are going to
describe further.
It’s time to talk about workflow optimization, and what you can do to
make sure your team can do its job correctly.

Your Typical Team

Usually, a documentation team consists of four main roles:

● A team lead – oversees the entire workflow, assigns tasks, and
is responsible for the project release. He or she also acts as a
representative of the team during the company’s meetings;
● Editors – review the documentation for logic flow and clarity;
● Translators – provide translations of documentation in other
languages;
● Technical Writers – conduct the research and write the
documentation.

79 Share this book:


Your Typical Workflow

Here’s how the average day for a documentation team looks: the
company hands the team an assignment (or multiple), usually
through the team leader. The lead then presents the job to the team,
offering relevant details about the project such as specifications,
goals, and deadlines, and assigns the tasks. Technical writers start
researching the topic and writing the content, which will later go
through the editors for checking.

When the documentation is final, the document goes through the
translation process if necessary.

That’s your typical day, without taking into account meetings,
presentations for clients or other tasks that might arise. One thing is
pretty clear, though: the people involved in creating documentation
aren’t working independently from one another, but are
collaborating to complete a project.

Instead of offering each person an entire assignment, the team
leader divides the project into smaller tasks. That way, the result is
an excellent documentation that is well-written and comprehensive.
However, the success of your documentation depends on having a
good workflow.

Two Steps for Optimization

Challenges can appear at any stage of the documentation process.
To avoid and overcome them, make sure that you implement the
following tips and help optimize your team’s workflow.

Create a Documentation Plan

80 Share this book:


A team works best if everyone is on the same page, tasks are divided,
and members know what they have to do. The easiest way to avoid
confusion is to create a documentation plan for each project. Include
the goals and deadlines, as well as who is responsible for each task.
The team lead will present the plan during a team meeting and make
sure everyone understood what they have to do.

Use Help Authoring Tools

If you want to improve workflow, then make sure that your team is
using a help authoring tool. They are designed to assist technical
writers, but you can also find programs that are created specifically
for groups. With their help, you monitor workflow and enable
members to collaborate in real time and become more efficient.

Check out the Teamwork and Project Management features of
ClickHelp as an example of what a HAT can offer. These are:

● Document statuses
● Automatic document locking
● Status notifications via email
● User roles to control permissions
● Advanced TOC filtering by assignee, status, etc.
● Per-topic review notes panel for internal comments

And more such-like features for co-authoring is just what you need
for the documentation team workflow optimization.

Conclusion

It’s rare to see them get the credit they deserve, as they’re typically
not linked with the company’s profitability. In some cases, however,
your documentation department can be the key to your company’s

81 Share this book:


success. However, that solely depends on their ability to keep up
with the tasks at hand. The tips presented above can ensure your
documentation team can do their work without glitches.

82 Share this book:


Documentation Team: How to Delegate Tasks

It’s time to accept the facts: you can’t do it all by yourself. As skilled
and task-oriented as you may be, juggling multiple projects at once
can take a toll on you. You need to let others help you and take some
of the pressure off your shoulders.

However, delegating tasks isn’t as simple as it may sound. You need
to find the perfect technical writer for the job so that the result is par
excellence. For example, if you are pressed for time, look for the
writer with the lowest workload and fastest work speed.

But, most importantly, you must avoid falling into one of these two
traps: micromanaging the entire user documentation process or
failing to supervise your team properly.
This article will teach you how to avoid getting caught in either one of
those scenarios.

The Basis of Delegation

You must learn how to assign clear tasks to your team, express
expectations, and set deadlines. You also need to implement a
tracking system that allows you to give autonomy to the person
completing the task, while still being able to supervise them.

Don’t get the wrong idea, though. You are still part of the working
process, and need to make yourself available for your team should
any question arise. User documentation can take a lot of complex
forms, depending on the subject or the intent behind the content, so
it is quite possible you will have to assign two or more people on that
particular project.

83 Share this book:


It is quite important for a manager to know what’s his team’s
capabilities are. Try using our blog post on key skills for technical
writers to analyse your own team. It is always helpful to keep this
picture in one’s mind.

The Five Steps of Delegation

Here are a few things that can help you ease the delegating process
and avoid any inconvenience.

● Assignments Are Individual: When you are telling your team
what they have to do, it’s more efficient to assign each task to a
person directly and check to see if everyone is on the same
page. Provide clear and accurate instructions, so that they can
complete their duties. For example, one person is responsible
for writing new topics, another one for making tutorial videos,
and so on.

● Give Them the Bigger Picture: It is always easier to work on
something if you know what the goals are. Especially when
we’re talking about a complex task like creating a knowledge
base, each team member should be aware of the outcomes
they need to deliver.

● Give Deadlines, and Stick to Them: It’s very important to tell
your team right from the start how much time they can work
on something. Explain the importance of them handing in their
work on time in correlation to other processes of your
business.

● Use Reports Periodically: When you delegate, you are not
actively taking part in the completion of each task, but you have
to have a sense of what is going on. The best way to do that is

84 Share this book:


to ask team members to provide reports of their work status.
As such, you can have an overview of the process and intervene
whenever you have to, thus allowing you to stay within your
documentation plan.

● Tell Them How They Can Contact You: Ideally, a weekly meeting
should not be the only chance your team gets to interact with
you. They need to know that in case something arises, they can
quickly get a hold of you.

It is necessary to mention that keeping most of such info in one place
is a great idea. So, think about creating a documentation plan to give
employees something to refer to.

Pay additional attention to your working environment - make sure
you have all the right tools for better and faster delegation. A lot of
help authoring tools contain features improving team workflow and
allowing more efficient task delegation, just like teamwork features in
ClickHelp.

It’s About Trust

Delegation doesn’t mean the manager isn’t working on anything. It
has more to do with the final result itself.

There is a level of trust that needs to exist between the delegators
and their team. No management technique can ever replace that.

85 Share this book:


Cross Team Communication for Technical Writers

If you’ve ever read documentation written by a programmer, it will
become clear pretty fast that creating user guides requires a whole
different set of skills. Sure, programmers might have the necessary
knowledge base, but most of them aren’t very apt in communicating
the information in a user-friendly manner. Thus, the user guides they
create are usually hard to read and comprehend.

It’s becoming more and more evident for companies that they need a
team of t echnical writers t o take on a documentation task.

However, most of the times, the documentation team is kept isolated
from the other teams, although cross communication and
collaboration are vital to fulfill an assignment adequately.

Just think about it: if your technical writing team is isolated, how can
it be able to deliver documentation for products if they are not fully
involved in the entire process?

It’s a hard task to ask of them, especially during a sprint, when
development is still not complete, and writers often have to create
documentation on an unfinished product.

That’s why, you must keep your technical writers in the loop.

Tech Writers Are Full-Fledged Members of the Team

Tech writers are a vital part of your team and have just as much to
do with the product you are creating as your developers, QAs, and
designers. In fact, tech writers need to be in constant communication

86 Share this book:


with other departments to do their jobs efficiently. Think about it this
way:

● If you involve them in the sprint planning, they could establish
tasks where additional documentation might be needed;
● If you want your tech writers to create proper documentation,
then you should coordinate them with the development and
testing teams;
● The documentation should serve as a marketing tool, so here
we go - a marketing team should be in touch with tech writers,
as well. In case this is a new idea for you, read this article called
Technical Writing as a Marketing Tool to figure out how to make
your user guides more profitable.

Communication Is Everything

You should encourage active listening. It’s one thing for your teams
to talk to each other, but are they really listening to what is being
said? Active listening implies that the receptors understand the
information that comes their way. That means no distractions and,
perhaps most importantly, not listening just for the sake of providing
a comeback.

Disagreements can appear at any time, but it’s vital for your teams to
know they can express their opinions freely and in a friendly matter.
At the end of the day, they all depend on each other to do a good
job, so they should know how to listen to each other and consider
every input.

Optimize the Process

No matter how well the teams can talk and listen to each other, they
also need the right tools to communicate properly. Though it’s vital

87 Share this book:


to have meetings where you brief teams on projects and plans, that
can’t be the only way they can talk. Other means such as e-mails and
phone calls are fine, but they won’t do much regarding efficiency,
especially when you have more than 2-3 people communicating.

Instead, you should be considering a communications app designed
for this purpose. Even some help authoring tools provide this
feature, and they’re great for keeping everyone updated with the
steps of a project. You can check out ClickHelp as an example of a
HAT providing a lot of features for team communication and
management.

It Works to Your Benefit

Documentation is not just the final piece of the puzzle, and especially
not one you can do last minute. If you want teams from different
departments to collaborate efficiently, then you need to ensure that
they can communicate easily. Only then, you’ll begin to see
improvements.

88 Share this book:


Conclusion

Technical writing is not easy, but this job is available for everyone.
You might think that you need to be a Jack-of-all-trades to suit the
position requirements for the job, but it is not true.

In this career guide, we’ve gathered our personal experience and the
very gem pieces of advice throughout our 10+ years careers in the
field of technical communication. We sincerely hope that this ebook
inspired those unfamiliar with the field, encouraged those uncertain,
and gave established technical writers and communicators new
directions for development.

Leave out all the hesitations and start a career in technical
communication!

89 Share this book:


90 Share this book:

Technical Writer Career Guide

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Technical Writer Career Guide

Încărcat de

Drepturi de autor:

Formate disponibile