Southern Communicator

Transcription

The Australian and New Zealand Journal of Technical Communication
Southern Communicator
ISSUE 27
ISSN 1832-0120
OCTOBER 2012
Professional Development and
Recognition of Technical Communicators
Technical Communication Body of Knowledge
Getting the Most out of your Subject Matter Experts
Designing for Mobile Devices
Multi-Language Online Publishing made Easy
The Magic of Threes and Readable Text
Where is my document? A different view
1
Contents
2
From the Editor’s Desk
Janet Taylor
3
Foreword: Certification – A Pathway to Professionalism
4
Professional Development and Recognition of Technical Communicators
Steve Moss and Sue Woolley
8
How to Write…Effective Brochures
9
Getting the Most out of your Subject Matter Experts (SMEs)
Tony Self
Jonathan Kranz
Lynne Laracy
11 Certification the STC Way
13 Multi-Language Online Publishing made Easy
Ana Young
Alex Johnson
15 Designing for Mobile Devices
Sofie Bird
17 Tricolons, the Magic of Threes and Readable Text
Simon Carter
19 Where is my Document?
20 Technical Communication Body of Knowledge (TCBoK)
Paul Trotter
Steve Moss and Sue Woolley
23 Web Tips
Ben Hunt
24 PowerPoint − One PC, Two Views
2
Frank Munday
Housekeeping
Editorial team:
Sue Woolley, Howard Silcock, Janet Taylor, Jeff Sneddon, Samantha Jones and Steve Moss.
Final
Proof reader:
Steve Moss.
Copyright:
Articles remain the copyright of the author.
Cover:
Sue Woolley.
Disclaimer:
The views expressed in articles in this journal are not necessarily those of the editors.
Contact:
Send any contributions, letters, subscription or advertising queries to [email protected].
Southern Communicator is a joint publication of:
Australian Society for Technical Communication (Victoria).
www.astcvic.org.au
Technical Communicators Association of New Zealand.
www.tcanz.org.nz
Australian Society for Technical Communication (NSW).
www.astcnsw.org.au
SOUTHERN COMMUNICATOR
ISSUE 27, OCTOBER 2012
2
From the Editor’s Desk
by Janet Taylor
Certification has been exercising our minds for many
years. Are we getting closer to a resolution? Should we
develop our own Australian/New Zealand scheme, with
very limited resources or adopt one of the programs that
have been developed elsewhere?
Sue Woolley and Steve Moss, presidents of ASTC (Vic)
and TCANZ, respectively, have made some forward
progress in defining what we technical communicators
consider are required skills and abilities and you will find
their summaries in two articles. Ana Young has been
investigating the certification program offered by STC (in
the US) and Tony Self introduces a program that he has
been involved with, developed by tekom in Germany.
Besides certification, we have some really interesting
articles in this edition.
Jonathan Kranz tells us how to write effective
brochures. I hope this will persuade you to widen your
scope of work and certainly use the knowledge when
selling your services.
Lynne Laracy gives some very sensible advice,
delivered in a light hearted way, about getting the most
out of our SMEs. Too often, in spite of trying to achieve a
common goal, the SME/technical communicator
relationship becomes a war zone.
I must admit it: I'm a happy Flare user. The article by
Alex Johnson was written for us and I can say that the
Flare people didn't interfere with it or embellish it.
If there is only one article that you read in this journal, the
one about mobile devices by Sofie Bird should be it. No
matter what output medium you produce for now, you
can be absolutely certain that sooner than you think it will
need to be displayed on a mobile device. This is a very
important topic and you will be wise to prepare for the
change now.
I first read Simon Carter's article about tricolons three or
four years ago but I just couldn't see myself using them in
written work. We asked Simon to rewrite his article with
emphasis on using tricolons in writing. He did, and what
we have, unexpectedly, is a very useful article about
making our writing much easier to read.
Paul Trotter is a man with a mission and he's developed
a wonderful product, Author-it, based on his vision. Read
his article and learn how you can benefit from Author-it.
For some time I've wanted to introduce you to Ben Hunt.
Ben is totally generous in sharing his knowledge and
offers to email you 50 web tips, one per day. I found
every one of the tips really useful, and not just for web
development. See how to subscribe on page 23.
On the back page is the second part of our article by
Frank Munday, showing that PowerPoint is not just a
slide-maker. I'll bet this is one technique that you don’t
already know about.
I really hope you learn as much from this issue as I have
and that you enjoy reading it. I did!
Housekeeping
Submission guidelines
Articles
Advertising
We welcome articles on all aspects of
technical communication.
The author’s biography is printed at
the beginning of the article so that you
can easily see whether the author is
affiliated with the product or service
they are writing about. You can then
make your own decision about
whether the information in the article
is of interest to you.
Advertising rates:
Full page: AU$200, Half page: AU$100
Quarter page: AU$50
Business card size: AU$25.
Please submit articles following the
‘Contributor’s Guidelines’, obtained
from www.astcvic.org.au
Contributors are responsible for
obtaining permission to reproduce any
third-party copyright material used in
their articles.
Articles may be edited for space
considerations or to meet other
publication requirements.
When submitting an article, please
include a short biography and
photograph of yourself and
send it to: [email protected]
Distribution
Southern Communicator is
published three times a year.
If you are a member of
ASTC (Vic), TCANZ,
or ASTC (NSW), you
receive this journal as one
of the benefits of membership.
Advertisements will be clearly marked.
The author of the advertisement will be
responsible for the accuracy of the
content. Direct advertising enquiries to:
[email protected]
Next issues and Deadlines
February 2013:
Deadline January 6.
June 2013:
Deadline May 4.
October 2013:
Deadline September 5.
3
Foreword: Certification
A Pathway to Professionalism
by Tony Self
Dr Tony Self has over 30 years of experience as a
technical communicator, 20 of them working in the
areas of online help systems, computer-based
training, and electronic documents. In 1993, he
founded HyperWrite, a company providing training
and consultancy in structured authoring, Help
systems, DITA, and technology strategy. Tony
completed his PhD in semantic mark-up languages in
2011, and his book The DITA Style Guide was
published in the same year. He is a member of the
OASIS DITA Technical Committee (and chair of the
DITA Help Subcommittee), and won the ISTC Horace
Hockley award in 2011.
He recently started as Director of Training for
TCTrainNet.
To be truly professional, technical communication needs
formalised training, certification of competency, and
ongoing professional development opportunities.
Some universities require their lecturers to have higher
degrees. Some accounting companies require their
accountants to be certified and have their skills updated
annually. It tends to be unskilled occupations, such as
cleaning, data entry, bar tending, and fruit picking, for
which certification is not the norm. (Bar tenders may need
government-mandated certificates in food handling and
responsible service of alcohol.)
In some countries with established and entrenched
university education for technical communicators, such as
Finland, the occupation is very professional in most
senses of the word. In other countries, the lack of
education and training has seen technical communicators
behave more like an unskilled occupation than a highly
skilled profession.
Interestingly, practising technical communicators would all
like to see themselves as professionals – as members of
In theory, to become a technical communicator, all you
a recognised profession. Many technical communicators
need to do is visit your local quick print shop, and order
do seek out education and training courses, earn
100 business cards with
themselves recognised qualifications and
Technical Writer printed under
join professional associations. But many
“Two weeks ago I couldn't even
your name. This is not illegal,
do not have access to training,
spell
‘technical
writer’,
as far as I know, in any
qualification, and certification.
and
now
I
are
one!”
jurisdiction in the world. You
For the professionalism of technical
don't have to be a member of a
communication to be raised, we need greater access to
professional association or a union, you don't have to do
training, and certification standards. This would not only
any study, you don't need any government authorisation,
help individual communicators, but also help employers to
and you don't have to pass any exams.
employ competent and qualified communicators – and to
My dictionary describes a profession as “a paid
avoid those who have just visited the quick print shop.
occupation, especially one that involves prolonged
In her book The Rise of Professionalism: a Sociological
training and a formal qualification”, but there are other
Analysis, Magali Sarfatti Larson1 identifies a number of
meanings, many of which have a cultural basis. A
characteristics shared by occupations regarded as
professional engages mainly in administrative and
‘professional’:
intellectual labour, while by contrast a tradesperson
“The visible characteristics of the professional
engages in manual labour. Sometimes, professional may
phenomenon [include] professional association,
refer to a white collar worker, and tradesperson means
cognitive base, institutionalized training, licensing,
blue collar worker; the distinction is to do with social
work autonomy, colleague ‘control’, [and a] code of
class.
ethics.”
For many professions and trades, there are government
regulations that help define the occupation. A medical
doctor has to be qualified and registered. An electrician
has to be qualified and registered. A builder has to be
certified. A police officer has to be trained, tested and
sworn in. If there are no government rules defining an
occupation, employers apply their own standards.
If there are no government rules defining
an occupation, employers apply their
own standards.
Larson also suggested that professions have a more
extensive group allegiance than other occupational
groups.
Please turn to page 5 where Tony describes the
TCTrainNet certification offering that he believes is an
option for Australian Technical Communicators.
1
Larson, Magali Sarfatti (1979) The rise of professionalism: a
sociological analysis. Berkeley. University of California Press.
4
Professional Development and
Recognition of Technical Communicators
by Steve Moss and Sue Woolley
Professional development and
recognition working group
Late last year, a working group was formed to look at
professional development and recognition of technical
communicators in Australia and New Zealand. Currently
the working group consists of:
•
•
•
•
Sue Woolley, ASTC (Vic), Chair
Steve Moss, TCANZ
Rob Phillips, ASTC (NSW)
Bede Sunter, ASTC (NSW).
The mission of this working group is to:
1.
Investigate what options are available for people
who want to start a career in the technical
communication field in Australia and New Zealand,
including training and mentoring.
2.
Investigate what training options are available for
technical communication professionals to develop
and maintain their skills.
3.
Establish whether providing a new ASTC or TCANZ
membership grade, that recognises experience and
qualifications, would be useful to members or
employers of those members.
4.
5.
Establish whether a certification scheme for
technical communication professionals in Australia
and New Zealand would improve our employment
prospects, remuneration and professional standing.
If required, report on options for a certification
scheme including:
•
pros and cons of existing schemes (such as
those provided by tekom and STC)
•
what is feasible for our region
•
what sort of training needs to be available for an
individual to maintain their certification status.
After considerable discussion between members of the
working group, it was decided to leave out items 4 and 5
above. There were several reasons for this. Firstly,
because STC and tekom (the German TC organisation)
had recently introduced their own certification schemes
and we wanted to monitor developments on those
schemes before considering introducing a local scheme.
Secondly, due to the complexity and expense of setting
up a certification scheme, the group were concerned that
the resources available between our local organisations
may not be adequate to develop our own scheme.
ISSUE 27, OCTOBER, 2012
Survey
We decided to issue a survey to find out the views of
technical communicators, employers and placement
agencies. This will help the societies to assist their
members by providing meaningful ongoing professional
development opportunities, and to investigate the
provision of enhanced membership grades and a
mentoring scheme.
We saw this as an opportunity to increase members’
knowledge and skills and to gradually improve the
perception of our profession.
Overview of survey
During June 2012, three surveys (one each for technical
communicators, employers and placement agencies)
were distributed to ASTC (Vic) and TCANZ members,
and an additional invitation was sent to Austechwriter
members. Responses were received from 48 technical
communicators in Australia and 52 in New Zealand, from
14 employers (in total) and from 8 placement agencies in
Australia and 1 in New Zealand.
The aims of the survey were to find out the:
•
•
•
•
level of support for an 'enhanced membership grade'
of the local society
level of interest in a mentoring scheme
requirements for various types of professional
development, including academic qualifications,
semester-long modules, workshops, short courses,
conferences and so on
importance of different skills.
Summary of conclusions
Enhanced membership grades
There is a strong level of support from practising
technical communicators for an ‘enhanced membership
grade’ (EMG) to be made available by their local
society. However, both the employers and placement
agencies indicated that they would be unlikely to pay
more for a person with an EMG, but that it could assist
them in selecting a candidate for a position.
Based on this feedback, ASTC (Vic) and TCANZ will
start investigating how such a scheme can be set up,
taking care to ensure that we address concerns raised
in the survey and that we consider the needs of all
members. Once a draft scheme has been designed,
further discussions will be entered into with stakeholders
to ensure that the scheme is workable and relevant.
PROFESSIONAL DEVELOPMENT AND RECOGNITION OF TECHNICAL COMMUNICATORS
5
Mentoring scheme
Skills requirements
Approximately half of the respondents were interested in
participating in a mentoring scheme, either as a mentor
or a mentee.
Both the employer and placement agency responses
clearly indicated that the top four skills required are:
Both ASTC (Vic) and TCANZ will start investigating what
would be required to set up a very basic mentoring
scheme.
2.
Structuring complex information.
3.
Soliciting information from SMEs (interviewing skills).
4.
Relating well to clients and the team.
Professional development requirements
The general view is that specific skills, such as tools, can
be easily taught if the person has the above skills and
personal attributes.
Only 6% (Aus) and 11% (NZ) of respondents are
currently enrolled in an academic qualification in
technical communication. 39% (Aus) and 57% (NZ)
indicated that they might enrol in future. The difference in
Australian and New Zealand responses probably reflects
the fact that there is no longer a specialist technical
communication qualification available in Australia.
Considerable interest was shown in the possibility of
enrolling in semester-long learning modules for in-depth
study in a topic that does not necessarily lead to an
academic qualification.
Based on these results, ASTC (Vic) and TCANZ will
investigate the possibility of a tertiary institution providing
individual semester-long modules.
Considerable interest was shown in the six different
survey suggestions for professional development,
including short courses and webinars. The societies will
analyse the results to determine which topics are of most
interest, and will plan their professional development
offerings for the next year accordingly.
1.
Writing and general communication skills.
Based on this information, the societies will follow up with
third-party providers and respondents who indicated that
they would be interested in developing short courses in
the most requested skills areas.
Where to next?
This article has not addressed the vexed question of
certification. In Australia, this topic has been raised again
and again, but no conclusion is ever reached. We now
have two global technical communication societies that
have English certification schemes, the US society, STC,
and the German society, tekom. With around 500 ASTC
and TCANZ members in total (compared to 12,000 in
STC and 26,000 in tekom), we may not have the
resources to be able to develop our own local scheme.
Once the Professional Development and Recognition
working group has addressed items 1-3 of its mission, we
can begin to investigate certification in Australia and New
Zealand. Do we endorse one of the global schemes, or
consider trying to create a certification scheme of our
own? Or do we consider other options for professional
development?
See the following pages for results of the survey.
A Pathway to Professionalism continued from page 3:
Applying the principles I’ve outlined on page 3 to ourselves,
to be truly professional, technical communication needs to
have:
•
•
•
•
•
•
•
•
professional associations such as tekom, STC, ASTC,
TCANZ, and so on
standards and agreed best practices
formalised training through universities, training
providers, and professional associations
certification of competency
clear definitions of what technical communicators do
a code of ethics
ongoing professional development pathways
professional pride.
To its credit, tekom, the German professional association
for technical communicators, has made great progress in
working towards greater professionalism. However, in the
English-language domain, there is still much to do.
Through the tcworld subsidiary, tekom has developed
two extremely important services: formalised training,
and certification. These services are being promoted as
TCTrainNet.
TCTrainNet offers three levels of certification: first level,
advanced, and trainer. Training for first level is all online,
with students guided by an experienced online trainer.
Training for advanced and trainer level certification is
more like coaching, with a trainer helping the student
develop skills through self-study, learning activities,
tasks, and group work. The tekom certification exams
are conducted separately from the training, to assure the
integrity of the certification process.
A pilot group of around 70 students has already been
through the TCTrainNet system, and there are now
tekom-certified technical communicators working in
many countries, from Poland and Britain to Japan and
India.
For more information about TCTrainNet, please visit
www.tc-train.net
6
New Zealand
Support for enhanced membership
grades.
Interest in semester-long learning
modules.
Number of people working in technical
publications in your organisation.
7
Australia
Exercise Your Eyes
Michelle Bridges, Sun Herald
magazine, August 2012.
•
•
•
Extend your arm with your
thumb up. Focus on your thumb
and keep focusing as you
slowly bring it to your nose.
Hold for three seconds, then
return to the start position.
Imagine a figure eight on its
side three metres away. Use
your eyes to trace its shape
three times one way, then three
times the other way.
Rub your hands together to
warm them up, then put your
palms on your cheekbones and
your fingers on your forehead,
cupping your eyes in your
palms. Let your eyes relax in
the darkness.
Reprinted with permission.
8
How to Write...Effective Brochures
by Jonathan Kranz
Jonathan Kranz is the author of Writing Copy for Dummies, and is the principal of Kranz Communications,
http://kranzcom.com, a marketing communications and public relations writing firm specialising in B2B and
consumer services marketing. He offers customised in-house and on-site marketing and PR seminars, and is a
popular speaker at professional association events, meetings, workshops and conferences,
http://kranzcom.com/speaking.html
Why produce a brochure?
Brochure projects are the vampires of marketing. All too
often, they drain the blood out of our budgets without
adding life to our sales. Why? They're expensive. They're
misused. And for people too lazy to think, they're the
standard default when it's time to ‘do something’ to help
market a product or service.
Brochures are poor sales devices. (For that, look toward
letters and other offer-centric vehicles.) But they do one
thing really well that can help support the sale: when the
product isn't literally in front of the customer, it figuratively
puts the product or service in the prospects' hands. The
more vivid the illusion, the more effective the brochure.
Here's how you can do it
Describe alternative uses
The more things your product or service can do or offer,
the greater its value. The primary use of the Split-All, for
example, would be chopping wood for fireplaces and
stoves. But perhaps it could be a way for customers to
make a little moonlighting money on the side - Turn your
cleared land into cash! - or to help them clear that land in
the first place.
Use charts, graphs, illustrations and
photos
As a professional writer, I'm loathe to admit it, but yes,
sometimes a picture IS worth a thousand words. Be sure,
however, that your captions tie your illustration back to
the sales message: In just one hour, the Split-All builds a
stack of wood equal to two weeks of winter heating fuel.
Tell a story
Paint a word-picture in which the reader can imagine
themself using the product or service to their advantage:
Within minutes, the whisper-quiet Split-All reduces tons
of timber into convenient piles of lasting fireplace fuel.
Simply elevate the rear axle of your truck, replace your
tire with our patented SpinLock Connector, then ...
Bring out the features
I know you've been told a million times to turn features
into benefits. True enough. But you have extra leg room
in the brochure. And you need concrete things to flesh
out your picture. This is the right time and place to list
your product or service features: Comes complete with
two safety chucks, a lifetime greaseless action bearing,
three special blades for hard, soft and 'wet' woods, and a
FREE 30-minute video that will have you cutting wood
like a pro.
Weave in the testimonials
Don't list them in a sidebar. Don't save them for the end.
Use them as callouts throughout the body copy to
reinforce your points across your entire sales story.
As a professional writer, I'm loathe to
admit it, but yes, sometimes a picture IS
worth a thousand words.
And ALWAYS have a call to action
It's not enough to be informative. By the end of the
brochure, make it absolutely crystal clear what customers
need to do get your product or service. And be literal
about it! Tell them to call and give them the number and
business hours; or list your URL or direct them to a local
dealer; or tell them how to find a local dealer, and so on.
You can contact Jonathan via [email protected]
Writing Copy for DUMMIES
by Jonathan Kranz
isbn: 768-0-7645-6969-2
is a print-on-demand book
available from
www.Amazon.com
9
Getting the Most out of your Subject Matter Experts (SMEs)
by Lynne Laracy
Lynne Laracy is the director of Laracy
Communications, an Auckland-based businesswriting and plain-language consultancy. She now
spends her days training SMEs to write better.
Meet Max. He’s the finance guy in charge of pulling the
annual plans and reports together. Meet Jane. She’s the
technical communicator in charge of making sure the
documents read well, look great, and do good things for
the organisation’s brand.
Put your heads together at the start
Initial planning is often done separately, in the different
camps. If the planning is done together, it is more
effective, has a broader perspective, and hopefully, more
buy-in. We can ask the usual document questions,
wearing different hats.
•
Matt and Jane are very nice people, and excellent at their
jobs. However, they are about to make each other’s life a
nightmare. Their shared projects – of producing highquality organisational documents – are about to become
a battle ground.
•
Why is this? Surely their aims are the same. Well, yes…
and no. Like everything, it’s a matter of how we see the
world, and what we care about.
•
So how can we avoid ‘blood on the floor’, as we work with
our subject matter experts to create great documents?
Here are a few things I’ve learnt along the way.
Understand that SMEs are from Uranus
and communicators are from Pluto
Apologies to John Gray for messing with his book title,
but in my experience, we and our SMEs often seem to
come from different planets.
When Max and Jane did the Herrmann Brain Dominance
(personality and thinking styles) tests in their
organisation, they were in opposite corners.
•
Max is in the blue corner (analytic, logical, mathematical),
while Jane is in the red corner (interpersonal, emotional,
verbal). When the going gets tough, he gets detailed and
nit-picky; she gets emotional and verbal. He’s a bulletpoint kinda guy; she’s a narrative gal.
As good communicators, we know we need to adjust our
communication styles to suit our audience. We excel at
this when we write, but can forget about it when dealing
with our document project teams.
We need to remember that we are the right people for our
respective jobs. Picture an annual report produced solely
by the finance team. Equally, a report that looks fabulous
and is a joy to read, but that doesn’t have the sums right,
is no good either.
Appreciating and harnessing what everyone brings to the
project, not only in terms of knowledge, but in terms of
world view and personality, is a crucial first step.
•
Who is it for? This is not only the end-reader, who
often occupies communicators’ thoughts, but may
also be auditors or other arbiters; industry observers;
industry award judges; political or organisational
masters. Our SMEs can bring us valuable insights
into some of the hidden audiences, and those that
share their expertise or world view.
Why are we producing it? Consider what the SMEs
think the purpose, or best outcome, for this
document is. It may be different to our view.
How will we present it? Getting agreement on
design, layout and language is not always
straightforward. SMEs often don’t care about many
of the things that exercise us. They can see design
as irrelevant ‘prettying-up’. The push for plain
language can be seen as ‘dumbing down’ their
message. This is our chance to educate them, with
some good facts to back up our assertions, about
how clear structure, layout and language are crucial
to get their message across.
When is it due by? A robust, agreed timeline,
working back from the publication date is critical to
the success of any document. It must have clearly
allocated responsibilities and take into account time
for peer review, editorial revision, and each sign-off
stage with its associated rework. That being said,
there is never enough time, and there are always
competing priorities. Therefore, the more managers
are involved in setting timelines, the better. They
need to agree to prioritise the work at crucial times
and to ensure that there are consequences for those
who consistently do not deliver to deadline.
What is the content? Brainstorm to bring a fresh
approach to content, and then decide who will
produce it. Consider using templates with strong
guidelines on word count and level of detail. Get to
know your content experts, and guide them in the
early stages of writing to produce information that
requires as little rework as possible.
After the initial planning phase, have regular update
meetings, and communicate regularly with the SMEs and
their managers.
10 GETTING THE MOST OUT OF YOUR SUBJECT MATTER EXPERTS (SMES)
Share desks and the muffins
If possible, work in the same space as your SMEs. You
can’t beat ‘over the divider’ conversations for efficiency
and for creating a sense of one team. If that’s not
feasible, try to find ways to work together on some parts
of the project to prevent a ‘them and us’ atmosphere.
Make it really clear who is responsible for what. There is
nothing more frustrating than having your beautifully
plain, clear text put back into bureaucratic- or corporatespeak. Work at establishing your credentials as the word
expert. Be pragmatic, not dogmatic. Learn to let go of
some things, even if they are your pet writing hates; it
shows you are listening and that you are flexible.
you introducing error into the text. Have robust version
control systems, to ensure everyone is working on the
latest version.
It helps to ‘work into’ the field. Put in some time to learn
what content-specific terms and concepts mean. This
puts you in a better position to translate their text into a
readable form and reduces the scope for introduced error
(which undermines their confidence in you). If you ask
your SMEs directly, they often feel that you are taking
their content seriously. This will ease the process further
down the line and build good relationships. Trust comes
over time.
Use good project management tools and principles. Often
SMEs can relate well to this – but would not think of
applying it to a writing task.
Prepare a brief style sheet
If you don’t understand something, ask before rewriting
(and maybe offer up your ‘best guess’ version). This
helps them feel involved, and reduces their fear about
‘blue’ colleagues. Collective amnesia about deadline
dramas, facilitated by wine, has been useful.
To save endless debates about the small stuff, give your
SMEs a really brief style guide – one page or so. Stick to
the points that cause the most rework such as
Help your SMEs become better writers
capitalisation, how the organisation is referred to, the
Most SMEs hate writing. Many went into technical
active voice, and list and heading styles. If they are true
disciplines to escape the long
‘blues’, they will stick to the rules. Make
shadow of their English teacher. A
your plug for plain language. Consider
Learn to let go of some things,
lot of them simply don’t care about
doing a road-show to your content
even if they are your pet writing
the finer points of grammar. What
contributing groups. But keep it short
hates; it shows you are listening
they do care about is accuracy and
and light-hearted, with some quizzes or
and that you are flexible.
detail, and producing a quality
something interactive. Remember,
product. And they usually care about
many don’t care about this stuff.
being professional and advancing their careers. Those
are great touch points as you work with them to provide
Involve them in the fun stuff
you with better content. Keep the messages simple.
For many SMEs, working with the creative team is new
•
Readers don’t want to work hard; they want short
and exciting. If they can see some of the process, they
sentences, easy-to-understand words and a clear
are less inclined to think that printed documents happen
logical structure. Short sentences mean the grammar
in the blink of an eye. This may help with getting
and punctuation are less likely to go wrong.
compliance with deadlines. A trip to the design studio or
•
Readers skim and scan, so creating an inviting, open
the printers can engender new respect for the expertise
layout with lots of signposts will help ensure the
involved and create a sense of being part of something
important content is not missed.
quite special.
•
It’s essential to tell readers the facts accurately and
Drink lots of wine
succinctly but most of all, it’s crucial to tell them what
the facts mean. It’s the SME’s job to give context to
In the end, this is a relationship. Shared time, some of it
the information and to help the reader make sense of
social, can help bridge that planetary divide between you
it.
and your SMEs. Respect comes from understanding the
•
It’s a sign of professionalism and excellent control of
value that someone brings to a task. When blues and
your topic when you can explain complex ideas in
reds (and all the other shades) learn to talk and harness
clear language. Flashy language is often seen by
each other’s strengths, we produce great documents –
readers as grandstanding and covering up lack of
without the battle scars.
knowledge.
Max and Jane now know that they have more
commonalities than differences – including their shared
Don’t make editing a battleground
aims for their document. They look forward to sharing a
The SMEs also need to understand that editing is a
table at the next plain language awards dinner.
process. They will sometimes not see what we do as an
In her former role as publications manager at
improvement, or understand why we are even ‘fiddling’
Auckland City Council, Lynne was responsible for
with it. It’s helpful to explain at the beginning that you
ensuring the council’s publications were up to
may not get it all right the first time, so a conversation to
scratch. She confesses to being in the red corner,
clarify some points is often needed.
and is now very good friends with many of her former
11
Certification the STC Way
by Ana Young
Ana has been involved in technical communication
for over 20 years. As a long-standing member of the
ASTC (NSW), she was the newsletter editor and past
committee member, and has presented at its annual
conference. She is also a senior member of STC.
Much has been said about certification in the past few
years. Some technical communicators are for it and
some are against. So far, the ones against are winning:
no society has done the required work to put it in place.
Truth be told, setting up certification, especially Australiawide, is not an easy task. If you want to know how
difficult it is, ask the Societies of Editors. And, in my
opinion, certification will only be worthwhile if it is
Australia-wide. I see no point in getting any form of
certification if it is lost when you move to another state.
In North America, STC has recently introduced a
certification program. The following is a summary of what
I found during my research into this program.
Much as the Societies of Editors did, STC formed the
STC Certification Commission (STCCC). The STCCC is
an independent certifying agency specifically formed to
administer the Certified Professional Technical
Communicator™ (CPTC™) program. The aim is to
ensure that CPTC-certified practitioners have
demonstrated that they have the most up-to-date skills in
the industry.
What do you need to do to apply?
To apply, you need to:
1. Ensure that you are eligible.
2. Complete the application form, pay the application
fee, and wait for STCCC to accept your application.
(Note that all fees are non-refundable.)
3. Prepare your submission packet.
4. Submit your submission packet and pay the
assessment fee.
1. Eligibility
Please note that:
“Certification is available to all practitioners (that
work in English) who meet the eligibility
requirements. STC membership is not required for
eligibility.
You need at least a recognised secondary-school
diploma (or its global equivalent) and five years of
experience as a technical communicator.
“If you have fewer than 5 years of experience,
however, and would like to seek certification,
additional education might reduce the 5-year
residency requirement. That’s because completing
formal study in a degree program in technical
communication or a related or relevant field can
reduce the learning needed on the job − and reduce
the time needed to become a competent technical
communicator.”1
STCCC lists all the currently selected degrees that will
give applicants the additional education that might
reduce that 5-year requirement. Not surprisingly, they are
all North American based.
And, STCCC states
“It’s not that other degree programs are not valuable,
but they do not formally prepare students for work in
the field and, therefore, are not assumed to reduce
1
the learning curve on the job.”
If you have five years of full-time equivalent experience
working as a technical communicator and a degree that
is not currently listed, you are still eligible to apply.
Unfortunately, it is not clear if degrees outside North
America or indeed degrees that are in no way related to
writing (such as Computer Science) will be accepted. If
this is your case, you have to contact STCCC and wait
for their decision.
2. Complete application form, pay, and wait
This is an easy step. Just go online, fill the form, pay the
required fee, and wait for a reply from STCCC to proceed
or not.
The fee is US$99 for STC members and US$125 for
non-members.
12 CERTIFICATION THE STC WAY
3. Prepare submission package
4. Submit packets and pay
If you are given the go ahead, you have one calendar
year to submit your total package. The package consists
of packets of work samples, work artefacts, and
responses to questions.
The fee is US$595 for STC members and US$695 for nonmembers.
In your package, you need to demonstrate proficiency in
five areas of practice that map to nine submission
packets, which you then send to the STC.
You can be asked to resubmit all or part of the total package.
If this is the case, you have to pay extra for each packet that
you have to resubmit. The fee is US$100 per packet. If you
have to resubmit more than five, it is recommended that you
pay the whole submission fee (US$595 or US$695).
Areas of Practice
Submission Packets
1. User, Task, and Experience Analysis
1. Project Planning
2. Information Design
2. Project Analysis
3. Process Management
3. Solution Design
4. Information Development
4. Organisational Design
5. Information Production
5. Written Communication
6. Visual Communication
7. Content Development
8. Content Management
9. Final Production
Recertification
Conclusion
After achieving CPTC-certification, you need to maintain
it. You can do this in one of two ways:
1. Pay a maintenance fee: US$49 for STC members
and US$69 for non-members.
As a long-time STC member and a supporter of
certification, I was very interested in hearing about this
program. However, having read what is required, I must
admit that I will not be applying. Why?
2. Recertify every three years at no charge.
•
Note: If you neither maintain your certification nor retake
the exam, your certification expires and you are no
longer a CPTC.
For more information, visit the
STC Certification Commission website at
http://www.stc.org/education/certification/certification-main
•
•
•
Eligibility – My degree and certificates are from
non-North American education organisations. I
cannot see myself spending the time and effort
justifying why my degree and certificates are valid.
Submission Package – You have to submit at least
nine documents. If I treat each document as an
assignment (and why shouldn’t I?), this is a difficult
certificate to take as you have only one calendar
year. Most certificates in Australia have only four
subjects and, if you enrol in all four in a single year,
you are considered a full-time student. From
experience, I know that it is not easy to be a full-time
student, hold a full-time job, and be part of a family.
Costs – Even if I “pass”, I find the costs a bit high.
And you do not just pay once: to maintain it, every
year you have to pay a minimum of US$49 plus STC
membership or US$69.
Relevance – How relevant is this certificate in
Australia? Even if the company you are working for
is based in North-America, will the Australian branch
recognise it? Will other Australian companies
recognise it?
The process may not be as complex as it seems. In May,
STC announced that eight people had achieved
certification.
1
http://www.stccert.org/?q=node/135
13
Multi-Language Online Publishing made Easy
How Fitness First creates online guides in multiple languages
for 1 million-plus users
by Alex Johnson
Alex Johnson is the training and documentation lead
for Fitness First. Prior to joining the company in
2007, he worked as a bespoke software account
manager and developer. He also spent three years as
a tour leader for trips to locations in Asia, North
America, the Mediterranean and Africa.
At Fitness First, we have built one of the world’s largest
health and fitness club businesses by fostering superior
customer satisfaction and loyalty. However, ensuring a
consistent experience across 435-plus clubs serving
some 1.1 million members in 15 countries takes
coordination, communication, and most importantly,
support.
To facilitate this effort we developed our own web-based
membership management system called Members First.
Members First is used by all employees – from the CEO
to receptionists and membership consultants on the floor.
We complement this software with a web-based help
system and two online manuals, offered in different
languages and dialects, which are collectively used by
approximately 3,000 employees.
After evaluating the options, we determined that MadCap
Flare authoring software was the best for our purposes.
Any time you take on the task of managing three online
guides in multiple languages, there is tremendous
potential for redundancy and inconsistency. We have
been able to avoid those traps using the MadPak suite
from MadCap Software.
We purchased MadPak to use Flare, but discovered that
the MadPak suite included additional tools that we could
use. These additional tools are:
•
MadCap Contributor: allows SMEs to contribute
content in the correct documentation templates.
•
MadCap Analyzer: identifies where we can improve
the documentation’s quality and efficiency; and
•
MadCap Lingo: assists in translation and facilitates
localisation.
Streamlining content delivery
One of the most significant advantages in moving to
Flare is its single-sourcing approach to content. We only
need to create or update new or enhanced features
content, which typically takes just a few minutes to
publish to users. Additionally, conditional text and singlesource publishing in Flare allow us to create countryspecific versions of the documentation that take into
account such factors as different legal rules and modes
of operation − publishing them all from the same Flare
documentation project.
The ease of developing and maintaining our Members
First help system has led us to use Flare to deliver two
new online manuals in the last year. First guide is a
member experience manual providing employees with
information about how to run the business. It covers just
about every process and procedure that a Fitness First
staff member needs to know.
Migrating from print to online
The first online guide we rolled out was our product help
system to assist employees in using Members First.
Previously we published our guides in large paper
documents that were difficult for our employees to
navigate and difficult to maintain. 90% of the content was
screen captures, which meant that nearly everything had
to be rewritten (recaptured) whenever there was a new
release of Members First. This was a time-intensive
process with significant printing costs. We knew we
needed to make the move to an online system, and
identified what we wanted from an authoring tool.
More recently, we opened a Fitness First franchise in the
Middle East. To support them and future franchise
partners, we have created an online franchise manual
that includes everything about what a franchisee needs
to do to conform to the Fitness First brand standards.
The ability to continually update our online manuals is a
big advantage of working with Flare, since our business
is always changing. We roll out a new version of our
Members First software about every quarter, and at least
one of those each year is a significant new release. We
publish the online documentation for the software
updates to all the countries we serve. Additionally, we
make bi-weekly updates to our online manuals that
14 MULTI-LANGUAGE ONLINE PUBLISHING MADE EASY
Bringing localisation in-house
reflect other technical modifications or changes in the
business. In short, we’re never finished.
Our team also appreciates that no proprietary file formats
are involved in Flare as Flare is XML-based. This means
that our developers can help us with the documentation
and even extend Flare. For example, we use JQuery to
introduce deep zoom images and graphical navigation
features into our member experience manual. Flare’s
openness gives us a lot more possibilities.
Navigation made easy
Of course, the main driver for moving to online manuals
was to help users quickly find the information they
needed. Flare helps us on this front in a few ways.
First, using the WebHelp format, Flare enables us to
provide context-sensitive help using our online software
guide. As a result, someone using our Members First
online management system can simply single-click on a
feature in our online software to access the relevant help
topic that explains how to use it.
Two other features help users navigate the content in
both online manuals, as well as the help system. The
table of contents (TOC) automatically links all topics
together, so users can use it to jump to the topic they
need. Additionally, we use the DITA-style standard
relationship table in Flare, which lets us display a panel
at the bottom of a topic that identifies all the related
functions, processes and reports. A user can look at any
topic and see all the related topics in other parts of the
document without us having to edit the topic or the TOC;
1
it is a very easy way to provide useful links.
Employees tell us that it is easy to search our content to
get the information they need and that finally they have
documentation that is truly useful.
Enabling content contribution
MadCap Contributor allows different employees to
comment on content written in Flare and this simplifies
the review process. Contributor also enables our SMEs
to contribute content within templates that our team has
created. This facilitates the authoring process while
ensuring that the formatting and information links are
correct and consistent. This is not the case with content
supplied in Word doc format. The authoring by SMEs
represents a significant change from the past. Back then
one single author largely created all the content because
sharing one large document and maintaining consistency
was extremely difficult.
Now our SMEs can pop in and out of the documentation
task without having to set aside swathes of time, and
their content can be integrated much faster. This is a
major bonus! The member experience manual has had
up to ten different authors using the Contributor template.
Everything still looks consistent, and that’s important
because we put a priority on quality and standards.
MadCap Lingo has played an equally important role in
ensuring quality and consistency across the languages
that we currently support: UK English, Australian English,
German, Spanish and French. Prior to implementing
MadCap Lingo and Flare, we supplied English versions
of the print documentation to an external translation
company. They provided a one-off translation that there
was no chance of us re-using. However, MadCap Lingo
has made it easy to bring the translation in-house.
Now as soon as documentation is ready, I import it from
Flare into MadCap Lingo and then pass it onto our
translators. The resulting translations are lower cost,
more accurate, and more focused, and the product
knowledge that is acquired or required when reading and
translating the documentation is kept in the business.
Moreover, we have the flexibility to translate the priority
content and get the release out, rather than waiting until
all the documentation is complete.
[with in-house translations]...the product
knowledge that is acquired…when
reading and translating the
documentation is kept in the business.
The process works particularly well in Germany where
they use Lingo for their in-house translations to make use
of the translation memory from translations they have
already done. They send the translation back, and then I
do the final build. I really appreciate that MadCap Lingo
produces a translation using existing translated content
and then adds in English sections where translations
don’t already exist. It makes it very easy to focus on the
new sections that need translation.
Improving content quality
As a finishing procedure, our team uses MadCap
Analyzer to review the documentation and identify
issues. For instance, a large documentation project can
take hours to publish. Because we need to create
different language versions of the documentation, it is
important to keep the files as small as possible.
The first time we used Analyzer we realised that over half
of the 2,500-plus pictures stored in with the
documentation were not being used. We were able to get
rid of about 1,300 pictures without flipping through each
one individually. We’ve also been able to find and fix
content that links to nothing or broken links where
content no longer exists.
This has allowed us to reduce the file size while
constantly improving the quality of our online guides. This
makes a huge difference when the project is replicated
multiple times for all the combined countries and
languages. Most importantly, it is bringing a superior
documentation experience to our users.
1
This feature uses Flare’s little known Relationship Table that
sits in a MasterPage template.
15
Designing for Mobile Devices
by Sofie Bird
Sofie Bird is a technical writer and web developer at
KnowledgeDoc and formerly a lecturer in computer
science and software engineering at RMIT. She has
served on the Institute of Professional Editors
Accreditation Assessment Board, designing and
adjudicating the accreditation exam. She holds
Masters’ degrees in Communications, Commerce and
Computer Science.
Rethinking online content
Mobile devices are fast outstripping desktops as our
primary way to view information online. By 2014, it’s
expected the majority of internet activities will come from
phones and tablets rather than traditional PCs.
What does this mean for technical writers?
It means rethinking the way we deliver online content
such as web help, intranets and other information. Mobile
devices are much more limited than their desktop
counterparts, both in speed and screen size. A web page
that takes seconds to appear on a desktop browser may
take several minutes on a mobile, especially if the user
isn’t connected to a wi-fi network. A layout that looks
beautiful on a full-size browser may be cluttered and
impossible to use on a phone screen, and many elements
that are used on desktops like mouseover or right-click
don’t translate well to a touchscreen interface.
One of the old staples of web help design – the table of
contents frame – chews up valuable screen real-estate on
a mobile device and requires far more precision to select
a topic than a finger-tap allows. It’s nigh-unusable on a
smartphone, but few online help systems have a better
solution for navigation. As mobile browsing grows, more
and more users will be frustrated by the lack of mobile
accessibility in current help system designs.
New opportunities
Mobiles can open up incredible new opportunities. Almost
all smartphones now support HTML5 to some degree, and
JavaScript libraries such as Dojo and jQuery1 can offer
sophisticated interactive content and interfaces. Imagine:
•
•
•
Help systems that predict what a user is trying to do,
delivering the solution intuitively rather than forcing the
user to work out what they’re looking for before they
can find it.
Instructions that adapt themselves to the user’s exact
task instead of using generic examples.
‘Offline-able’ help systems that stay accessible and
functional even if the user loses their network
connection.
These are just a few of the ways in which we can take
advantage of the emerging mobile world. More intelligent
help systems, more intuitive content delivery and better
user experiences are where this technology is headed.
It’s time to stop thinking about mobile devices as the poor
second cousin.
Mobile delivery is the future of the web and it’s a radical
change. Forget the drama of converting your frames and
table layouts: mobile delivery requires a whole new
approach to content creation.
Considerations for mobile devices
Reduced bandwidth
It takes much longer to download files to a mobile device
than a desktop and Australian mobile users are typically
subjected to much stricter download limits on mobile data
plans. Content that contains a lot of images or uses large
image files is going to frustrate a user who has to wait
several minutes for the page to load. Unfortunately, most
help documents today use large screenshots and
diagrams to aid written instructions.
When writing for mobile devices, it’s always best to ask
yourself if you need the image in the first place – a wellwritten instruction will reach your user faster. Sometimes
images can be vital to an explanation; the trick is to
ensure that the resulting help files are kept as small as
possible. For example:
•
•
•
•
•
•
Keep your images as simple and clear as possible,
and keep colours and unnecessary detail to a
minimum. Not only does that make it easier for the
user to understand the image, but images without
gradients or lots of detail are usually smaller in file
size.
Crop the image down as much as possible, so you
aren’t showing the user anything they don’t have to
see.
Shrink the image to the actual size it needs to be in
the document using an image editing program rather
than forcing the browser to reduce the full-size image.
Downsample your images where possible to reduce
size without a noticeable change to the image. Most
image editing programs show you a preview of the
resulting image during downsampling so you can
balance quality and file size.
Choose a file format that is supported by all browsers
and provides good compression, such as GIF.
Avoid PNG files, which don’t play well with older
versions of Internet Explorer, and JPG files, which lose
quality each time the file is saved.
16 DESIGNING FOR MOBILE DEVICES
Higher latency
I’m going to get technical here, but hold onto your
keyboards, I’ll keep it simple.
traffic while walking, there are far more things trying to pull
their attention away.
The truth is, it’s not just that mobile devices have a slower
download speed. It also takes them a lot longer to ask for
the content to begin with.
Let’s be real, here – nobody enjoys reading on a tiny
screen: if they wanted a leisurely afternoon with your
website, they’d dig out their laptop. A mobile user is rarely
browsing; they have an aim in mind. Something has
caused them to pause, pull out their phone and start
looking up your information. They need to know
something and they want to know it quickly so they can
get back to what they were really doing. Hamper this goal
at your peril. Your content needs to be:
Latency is how long it takes to get a message (like “hey,
give me that file”) from the web browser to the server and
back again. Latency comes into play every time the web
browser asks for a file, such as a web page or an image
within that page. The latency of wired connections like
desktops is negligible – so much so that it’s generally
more efficient to split a large page into smaller ones.
That’s why news articles, comments or image collections
are often split into pages; with the minimal latency, it’s
faster for a wired desktop browser to request several
small files than one big one.
But the latency on a mobile device is much, much higher
– sometimes even higher than the actual download speed
of the file. So you don’t want that mobile sending
individual requests for a hundred tiny files, because it
ends up spending more time asking for the files than
actually downloading them. On a mobile device, splitting
up your content into separate pages can actually make it
less usable. One big page will download faster than two
dozen smaller ones.
Reduced screen size
Mobile phones and tablets have a much smaller screen
than desktops. You can fit, at best, a moderate-sized
paragraph of information on the screen at one time. This
means:
•
•
•
•
•
•
Images need to be less than 450 x 280 pixels to avoid
forcing users to scroll to see the rest of the image – or,
even worse, forcing them to scroll horizontally to read
your content.
Large headings and fancy markup that chew up space
need to be redesigned to be less obtrusive.
Navigation needs to be hidden unless required by the
user; the standard side frame of topic links eats up
almost the entire mobile screen.
Sentences and paragraphs need to be very concise. A
paragraph a few lines long quickly becomes a wall of
text on a small screen.
The most pertinent information should be at the top of
the page to reduce scrolling.
Pages should be kept as short and specific as
possible so users don’t get ‘lost’ in the page while
looking for their answer.
Reduced attention
When people are sitting at a desktop reading your
content, they’re there to read your content. There aren’t
many distractions, except other programs or websites
open on their computer. But mobile device users are
almost always multitasking when they get to your site.
Whether they’re holding a conversation, shopping, trying
to complete a task or even just keeping one eye out for
•
•
•
•
Concise and to-the-point
Easily findable and navigable
Clearly sign-posted so they know when they’ve found
what they’re looking for
Written in clear, easily understood language.
You need to work with the notion that your reader wants
to spend as little time as possible on your site and
probably has an eye on something else at the same time.
Balancing this with your business needs from the content
(for example, marketing and sales) takes careful design.
Web apps − the new way of the web
How do we reconcile the need for short, specific topics
with the need to download fewer files to reduce the lag
caused by latency? How do we create a navigation
system that’s there when we need it and hidden when we
don’t? Enter the new way of the web.
HTML5 opens up some amazing new capabilities, not just
to solve these issues, but to revolutionise how we deliver
content online. With JavaScript libraries such as Dojo we
can compress an entire help system down to a single file
– everything is downloaded in one hit onto the device.
There’s no more latency or waiting for pages to load
because everything’s already on the device when the help
system starts.
We can create fully-functioning applications that run
entirely in the phone’s browser, can save themselves to
the phone like a native app and even run offline when
there’s no internet connection available. Navigation
systems can be designed in any number of ways to
provide access to content efficiently (in both time and
screen space) and aesthetically.
Help systems can evolve from mere static content to an
interactive program that actively helps the user find
information quickly and easily. We can even create a help
system that interacts with the system it’s documenting and
start really blurring the line between telling a user how to
do something and doing it with them. It’s a whole new way
of thinking, and a radical change in how we design online
documentation.
1
A library is a collection of source code modules use to extend
the functionality of a program. By using a library, you avoid
having to code every feature from scratch and can be reasonably
assured the library code does not contain any bugs. Dojo is one
such library for JavaScript, most notable for its extensive bank of
user-interface and mobile-friendly modules.
17
Tricolons, the Magic of Threes and Readable Text
How two very different candidates use tricolons and readability principles
by Simon Carter
Simon is a UK-based clear-writing trainer and coach and managing director of One Three Four
(www.onethreefour.co.uk)
Tricolons: how they can work for
Obama, Romney, and you
Firstly, let me make a few things clear: Barack Obama
hasn’t asked for my help on his speeches; Mitt Romney
didn’t ask me about the 47%1 and Cicero never quizzed
me on the magic of threes.
everybody is doing their fair share, and everybody plays
by the same rules”.
in November 20081 that showed how
Obama’s speeches used tricolons.
But Romney’s campaign will be staffed
by sharp-minded folk, and they’ll have
weighed his style against Obama’s.
Maybe Romney’s people are betting that
their target voters think that this is how real presidents
talk. Maybe voters long for the sweet succour that longwindedness and poor readability can bring.
So the tricolon-count isn’t the be-all and end-all. The
phrasings – or, as I prefer it, the readability – matter too.
Did you see that? The paragraph above uses three
Read the two speeches one after the other you can’t help
points to add rhythm and emphasis (‘Barack Obama
but notice the difference between them. The Obama
hasn’t… Mitt Romney didn’t… and Cicero never’). That’s
speech has more bounce and zip while Romney’s
a tricolon – a trick that orators, speechwriters, and
thunders. Romney quotes Churchill in his speech and
spinners of all stripes use to make their writing flow.
you can hear Churchill’s rumbling diction in Romney’s
There you go. I just zinged you with another tricolon.
over-formal phrasings: “it has never acted less deterred”;
“emboldened our mutual adversaries”; and “the
Charlotte Higgins (author of From
perception of our strategy is not one of
Homer to the Hippocratic Oath, How
partnership, but of passivity”. Romney’s
Readability scores – like the
Ancient Greece Has Shaped Our
probably never heard Churchill’s view
tricolon count – aren’t
World) got me started on this tack.
that “short words are the best”.
everything…
but
they
are
She wrote an article for the Guardian
useful if you want to write
clearer text.
Higgins’ article explains that the
tricolon is one of several tricks of Roman oratory that
Obama uses in his speeches. These tricks work well on
our ear and brain, and they’ve been around for a long
time. Long enough for Cicero to have mastered them in
the first century BC. I thought it’d be interesting to
compare Obama and Romney’s use of tricolons, and to
look at how easy to read their speeches are. I know it’s
not fair – one’s a world-renowned orator, the other’s a
Republican candidate. But it offers some useful lessons
for business writers, and maybe for political leaders too.
I looked at Romney’s speech to the Virginia Military
Institute on 8 October 20123 and Obama’s speech at a
3
Denver campaign event on 4 October .
Not all tricolons are created equal
Romney’s sentences are 20% longer
and his speech is 24% harder to read
Readability scores – like the tricolon count – aren’t
everything, and I’ll explain how readability scores work in
a moment. But these scores are useful if you want to
write clearer text. And the most striking difference
between the speeches – that Romney’s is more verbose
and over formal – is borne out by the readability scores.
The scores show that:
Romney uses 20% more words per sentence.
Obama and Romney use tricolons at a similar rate, 5.8 in
every 1,000 words. But the real difference comes when
you look at how they construct those tricolons. Romney’s
speech is much more verbose – I’ll get to some numbers
in a minute – and this weakens the impact of his
tricolons. Here’s a Romney tricolon: “In short, it is a
struggle between liberty and tyranny, justice and
oppression, hope and despair”. Fine, if a bit ponderous.
Romney’s speech is 24% harder to understand.
But compare it to Obama’s tight phrasings: “That is not a
plan to create jobs. That is not a plan to grow the
economy. That is not change…”; and “We believe in a
country where… everybody is getting a fair shot, and
You can measure the readability of a piece of text by
looking at the average number of words per sentence,
and the total syllable-count per sentence. I’ve used two
tests developed by Rudolf Flesch, an American
A 12 year-old could understand Obama’s speech. But
you’d need three more years in school to understand
Romney’s.
Rudolf Flesch and Microsoft Word’s
readability tests
18 TRICOLONS, THE MAGIC OF THREES AND READABLE TEXT
readability expert (born 1911, died 1986), and his
colleague JP Kincaid. The tests are based on evidence
that hard-to-read text tends to have long, complex
sentences and lots of multi-syllable words. Long
sentences and a high syllable-count make readers lose
their place. Readers then have to go back and re-read
that sentence or paragraph. Or maybe they’ll just leave
the text, and go off and do something else.
So if you want to keep your reader reading, your text
should score fairly well in these readability tests. You can
find these tests in Microsoft Word. To give them a try,
check the box ‘show readability statistics’ under ‘proofing’
in ‘Word options’. Every time you run a spellcheck Word
will show you the readability scores for that text.
But don’t get too hung up on these scores (this article
scores a miserable 45.7 on the Flesch Reading Ease
test). These tests offer clues that point to problems and
you shouldn’t treat them as a rock-solid yardstick.
They encourage you to do two things that will make your
writing easier to read. They encourage you to write
shorter sentences and use shorter words.
Do this and your writing will be crisper, and easier to
read. And in a world where more and more of your text
will be read on a screen – and a tiny screen at that – you
really want to make sure that your text is easy to read.
Barack and Stevie – a tricolon-match
made in heaven
Way back in February 2009 Barack Obama gave Stevie
Wonder the Library of Congress’ Gershwin Prize for
Popular Song. In his speech he said that Stevie had
been the soundtrack to his youth, and added this tricolonform praise:
“Stevie has always drawn on the incredible range of
traditions in his music and, from that, he’s created a style
that’s at once uniquely American, uniquely his own, yet
somehow universal”.
That’s it right there. The power of the tricolon married to
crisp phrasing. And it also proves that like recognises
like: it was Stevie who filled 1970s dance floors with his
tricolon-chorused ‘Signed, sealed, delivered’.
1
Romney told wealthy donors at a Boca Raton, Fla. fundraiser that 47 percent of the country, President Obama's
supporters, don't pay income taxes; consider themselves victims; feel entitled to government handouts, and will never be
persuaded to take personal responsibility for their lives.
2
http://www.guardian.co.uk/world/2008/nov/26/barack-obama-usa1
3
http://www.nytimes.com/2012/10/09/us/politics/mitt-romney-remarks-at-virginia-militaryinstitute.html?pagewanted=all&_r=0
4
http://www.whitehouse.gov/the-press-office/2012/10/04/remarks-president-campaign-event-denver-co
19
Where is my Document?
by Paul Trotter
Paul Trotter is the founder and CEO of Author-it
Software Corporation, the world's leading provider of
component content management software. Paul
wanted to solve the problems that content writers
face. The result is Author-it, a topic-based, singlesource writing software with multiple outputs.
Paul is a popular speaker at events all over the world
on topics ranging from technical writing and help
authoring to content management and localisation.
reviewing the same piece of information at the same
time, and on your screen my changes are going to pop
up automatically. You can comment on those changes in
social network style, agreeing or disagreeing, and it’s all
part of the database record. You can’t delete them, you
can’t circumvent them, and the auditors can just go in
and see everything that’s gone into the creation of that
piece of information.
If you work at a business like a bank or a pharmaceutical
company that needs to have air-tight auditability, there
are steps you’re going to have to go through any time
you need to produce a document.
In other document management systems, they may store
a record of check-in and check-out, but they have no
record of who might have contributed to that document in
the interim – all they know is that you checked it out, and
at some point later you checked it back in again.
You’re probably going to start by writing a draft in Word
and sending it to a few people for comment. They’ll all
make changes here and there – some small, some not
so small – and a few will send it on to some other people
they think might want to take a look. Eventually people
will start sending the document back, and you’ll wind up
with a bunch of different versions that you need to
consolidate.
At that point maybe you need to have a meeting to
discuss that, or maybe you send an email around about
what you’re doing. That whole process forms part of the
record that needs to be audited, so people can go back
and see who agreed, who disagreed, who had no input at
all – and why.
Anyone with experience in this area knows it’s really
difficult to track who did all those changes when you’re
looking back as an auditor.
The problem is that your draft is being worked on in its
final form: as a document. With every other kind of
software – accounting, sales marketing software (CRM)
and so on – people have learned to work on the raw data
and not produce a deliverable until the end. With
documentation, though, most companies are still stuck
simulating the process they would use if they were
working with pen and paper.
In our Enterprise Authoring Platform system, reviews
happen in real time, online. Two people could both be
We can do this because we treat the document as a
product rather than a part of the process. I’ve talked
before about the death of the document, and I firmly
believe that this approach addresses the fundamental
problem at the heart of documentation: that people are
writing in an uncontrolled way.
The great thing is, once you accept this way of looking at
documentation, all sorts of things become possible. One
of our features (Author-it xtend) analyses a person’s text
input and offers suggestions of what they may be trying
to say, based on other data in the system. Not only does
it save time, it ensures everything is uniform so you don’t
have to keep checking and re-checking the same text.
Need a document in a different format? Select your
output and you’ve got it in seconds, without having to
worry about formatting or fiddling with your page layout.
I understand that what I’m asking isn’t easy. I’ve talked to
technical writers about the benefits of Author-it before
and when I’m walking them through the software they’ll
still be asking me, “but where’s my document?” When
they get it, though, it all makes sense. There is no
document. You don’t need it. The document is the
deliverable. It’s a new idea, and new can be scary – but it
also makes a lot of sense. And that’s what differentiates
the new ideas that go on to become standard thinking
from the new ideas that go on to become nothing.
Component Content Management Systems (CCMS)
A component content management system such as Author-it, manages content at a component level rather than at the
document level. Each component is only stored once, and could represent a single topic, concept or asset such as an
image, table, product description, procedure and so on. Each component is managed separately and has its own update
history.
With a CCMS, the challenge for technical writers is to move from writing book-shaped, linear documentation to writing
modular, structured and reusable content components.
20
Technical Communication
Body of Knowledge (TCBoK)
by Steve Moss and Sue Woolley
Technical communication is such a wide-ranging and
diverse profession that it is difficult to identify what it is
that makes us, as technical communicators, unique.
The aim was to try to identify the combination of
attributes, skills and knowledge that would be expected
of professional technical communicators.
What makes us different from journalists, from business
analysts, from other communications professionals?
There are many interesting and esoteric skills that can
arguably be included in our body of knowledge, but we
wanted to keep the initial BoK at a reasonably high level.
We didn’t want to drill down to the nth degree as we felt
that there is a point at which you get a diminishing return
– and lose sight of the overall picture.
In order to define this difference we decided to start
developing a Body of Knowledge (TCBoK) for our
profession. The US-based Society for Technical
Communication (STC) have had a TCBoK project active
for several years, but we felt that it was a valuable
exercise in itself to consider our own local skills, interests
and abilities, rather than simply copy what STC have
done.
Some occupations have identified standards and
accepted practice for the foundation of their profession,
for example, project management (PMBoK) and business
analysis (BABoK). The BoK can then be used to define
best practice and can, in due course, be a basis for
technical communication certification.
To begin the process of compiling a TCBoK, we held
brainstorming sessions in Auckland, Christchurch,
Wellington and Melbourne in May and June this year.
Once all the sessions were complete, we rationalised the
results and organised all the lists of skills and knowledge
into categories. All four sessions resulted in similar lists.
We ended up with the following seven categories which
we feel is a good foundation for our Body of Knowledge:
1. Writing
2. Research and analysis
3. Design, structure and layout
4. Editing and quality control
5. Output and publishing
6. Management, planning and organisation
7. Other skills, including computer skills, tools and
domain knowledge.
Figure 1. A diagram representing our main Body of Knowledge categories.
TECHNICAL COMMUNICATION BODY OF KNOWLEDGE (TCBOK)
Within each of these categories we recorded about a
page of related skills and knowledge.
There are obviously some core skills and knowledge that
we must all have. As we progress (in both years and skill
level), we will typically continue to add other useful skills
and knowledge to our toolkit.
The next step is to further break down the TCBoK into
the core skills you need to start in the profession as a
junior, the skills you need to acquire to be able to work
alone and then a further set of skills to become a master
craftsperson.
What is it that makes us different from
journalists, from business analysts, from
other communications professionals?
Interestingly, in addition to recording skills and
knowledge, the discussion at several of the brainstorming
sessions evolved into a discussion about how technical
writing differs from other types of writing, the types of
output that we produce and the “soft” skills and personal
attributes that members of our profession generally
exhibit.
It gradually became clear through the process of
analysing the output of these discussions that we all
have a similar set of personal attributes and interpersonal
skills and that we need these to be effective technical
communicators.
Brainstorming session results
The following sections are the lists that don’t specifically
relate to skills and knowledge.
The basic business need that we meet
•
Imparting / delivering information.
How we differ from other types of
communication/writing
•
•
•
•
•
•
Technical focus in many cases
Write to educate and inform
Objective, fact-based
Accurate, clear, concise
Information must be structured and presented so
that the audience can find what they need as easily
as possible
We target a specific audience so that they are able
to make decisions or perform tasks.
What we produce
•
•
•
•
•
•
•
•
•
•
Advertisements
Annual reports, Board reports
Blogs, tweets, social media pages/content
Bulk emails
Forms
Graphics
Health and safety compliance manuals
HTML coding/scripting
Information management strategies
Interactive guides
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
21
Intranet content
Management papers, proposals, tenders, RFPs,
RFQs
Newsletters
Phone help
Policies
Posters
Presentations
Processes and procedures (design and/or
document)
Product manuals / user guides
Quick start guides
Scientific papers / publications
Specifications
Standard operating procedures (SOPs)
Standardised, single-sourced content
Standards
Style guides, style sheets, templates
Surveys / quizzes
Training materials, education manuals / online
modules (self-paced learning)
Videos / screencasts – both screen capture and
story telling
Visual basic (VB) programming / macro design
Web content.
Typical personal attributes
During the brainstorming sessions, we asked participants
to list personal attributes that they thought were typical of
technical communicators. The attributes suggested
during the sessions are in the following list. These have a
strong relationship to the Myers-Briggs personality types
identified by Andrea Wenger. (See following page.)
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Accurate with good attention to detail
Adaptive and flexible
Analytical
Confident and assertive
Curious about the world and able to find anything
interesting
Diplomatic, patient, practical
Hard working, honest
Disciplined self-manager
Improver
Methodical and objective
Problem solver
Quick learner
Self-motivator
Well-read.
Able to:
•
•
•
•
•
•
step back and see the big picture as well as being
able to focus in on detail when required
distil information to an appropriate level of detail and
complexity for the audience
explain things well and at an appropriate level for the
audience
question / interview and mine for information
think analytically, and apply reason and logic
understand highly technical information.
22 TECHNICAL COMMUNICATION BODY OF KNOWLEDGE (TCBOK)
Interpersonal skills
•
•
•
Excellent communication skills – oral and written.
Empathy – for the budget holder, the end user, the
SME, the print-shop, the web guy and so on.
Responsive.
Able to:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
communicate with a wide range of people at all
levels of an organisation
listen, negotiate, persuade
engage with stakeholders
work collaboratively with others
function as a user advocate
direct clients who don’t know what they want
set expectations (what you need, what you can do)
recognise limits to our individual knowledge and be
clear about our level of subject matter expertise to
client
communicate value of technical communicators to
the business
make connections and facilitate communication
give and accept feedback graciously
mentor less experienced staff
presentation skills – train, present
manage people.
General business skills
•
•
Good general knowledge
Advanced computer skills.
Have the ability to:
•
•
•
•
•
•
•
use a wide suite of tools and learn new tools quickly
read and assess material quickly
step back and provide perspective and the big
picture
facilitate meetings
work effectively alone as well as in a team
add value to many aspects of the business
behave professionally and ethically, keeping
confidential information safe.
Conclusions
The working group discussions, the survey and the
brainstorming sessions have all provided us with a
remarkable insight into the individuals who make up our
profession. It has also been interesting to see the link
between the personal attributes identified, the MyersBriggs personality types and choice of career as a
technical communicator.
We still have more work to do on refining the TCBoK and
are keen for members to help us by providing further
insights into what it is that makes a successful technical
communicator.
By considering the skills, knowledge and personal
attributes of the technical communicators involved in our
brainstorming sessions, the technical communication
societies are now in a strong position to tailor their
professional development offerings to the needs of their
members.
You are very welcome to become involved in the
development of the TCBoK. See box at left for how to do
this.
Most technical writers are Myers-Briggs
ISFJ or INTJ personality types
Many of you will have heard of the Myers-Briggs
Indicator for personality types. Andrea Wenger, a
technical and creative writer who hails from North
Carolina explores how different types of writers
generally fit into specific personality types. In particular,
she states:
“Most technical writers are ISFJ or INTJ.”
“INTJ writers are single-minded in their pursuits. They
tend to envision the conclusion even before they begin
writing. With a talent for analysis, they’re skilled at
communicating about technical subjects.”
Andrea goes on to explore the writing process of the
INTJ personality type:
How you can become involved
The process of creating the TCBoK is a continuing one
and, as a professional technical communicator, your
comments and suggestions are welcome.
“INTJs may approach a writing project in the following
ways:
•
•
•
For how to send comments and view the latest draft of
the TCBoK, go to the TCANZ website and look in the
Membership > Professional Development for
Technical Communicators > Body of Knowledge
or
http://www.tcanz.org.nz/Membership/Professional+Devel
opment+for+Technical+Communicators/
Body+of+Knowledge.html
•
Are conceptualizers who tend to explore a narrow
topic deeply.
Like to work independently.
Are innovative problem-solvers who want control
over the product and the process. INTJs are
confident in their vision and want to bring it to life.
Are motivated by their personal vision. Original
thinkers, they have little regard for convention.”
Sourced from Andrea Wenger’s blog
(http://andreajwenger.com/2009/09/14/the-intj-writingpersonality/).
20
Web Tips
by Ben Hunt
Ben Hunt is an independent web consultant and over the last 15 years, has created hundreds of web designs for
companies, government and charities.
He is acknowledged as a thought leader in effective web design, web site marketing, and conversion.
Ben's free tutorials on webdesign have helped millions of readers learn web design techniques that work.
Ben has written several books and published many papers on web site design and use.
Ben's advice “There is no point designing a website just
to look good. Your site should get you business!”
You can use any (and all) of these factors to draw
visitor's attention to one thing or another.
On his web site, http://www.benhunt.co, Ben offers much
free material to help you create the most useful web site
for your purposes and offers 50 free daily tips.
If you try to draw attention to too many things, you will fail
to keep that attention, and that's bad news.
Here are two tips from the free tips that Ben offers.
I thoroughly recommend you subscribe1.
Tip #7 – Manage the eye (Nine
Noticeability Factors)
When someone comes to your web site, they should
quickly be able to scan the page and know "Yup – I'm in
the right place".
Some web pages are so busy that the eye simply can't
settle on the content. It skips around from one element to
another, and no information gets through. Then ‘ping!’
the clock runs out and you've lost the visitor's attention.
Look at your own web pages. Are they easy to look at –
AND yet visually appealing?
Some web pages just have too much shouting for your
attention, so your attention is fractured.
Others don't try to draw your attention anywhere, and
your attention is squandered – which is just as bad!
In order to fix either issue, you need to know the factors
that draw attention, and – then – how to balance those
factors.
Here are the 9 Noticeability Factors that I describe in my
book Save the Pixel:
1. Size
2. Colour
3. Contrast
4. Boldness
5. Space
6. Position
7. Dynamism
8. 3D effects
9. Content
So let every page have a focal point, a simple "Start
here" for every visitor.
Tip: The focal point should be the most instantly
noticeable thing on the page, and it should be in the
content. There's no point drawing attention to the noncontent features that are the same on all pages (like
branding and navigation).
Tip #47 – Share What You Can See
It's tempting to think that your experience isn't special,
that everybody else already knows everything you've
learned.
You have nothing interesting or valuable to blog about,
write a book about, or even sell.
On the contrary. Nobody else has your perspective. Your
story is unique, and I'll bet there are people right behind
you on the path who would benefit from your knowledge.
Sure, the things you learned a few years ago may be old
news now. But the herd has moved on. What are you
learning right now? What can you see from your unique
position on the edge of the herd? What can you share
with those following behind you, to help guide, reassure,
inspire, inform, or educate?
Time goes by, and the herd moves along. But your
particular perspective will always be unique and special.
Don't be afraid to share it.
1
To receive the 50 free daily tips, go to
http://www.webdesignfromscratch.com. Wait a few
moments and the sign up form will appear at the bottom of your
screen.
To buy Ben's books:
Save the Pixel – the Art of Simple Web Design,
Convert! and
How to be #1
go to http://www.benhunt.co/books
24
PowerPoint − One PC, Two Views
by Frank Munday
Frank ‘Choco’ Munday has been responsible for implementing end user documentation and training in many large
(and small) systems across the CSIRO, IP Australia and the Australian Federal Police (AFP). He is in demand as a
presenter at conferences, most notably the ASTC (NSW) conference.
PowerPoint has a Presenter View
that allows you to view your
presentation with speaker notes
privately on one computer (your
laptop, for example), while your
audience views the notes-free slide
show on a different monitor or
projected onto a larger screen. See
Figure 1.
Set up a presentation to
use presenter view
In order to use presenter view, your
computer must meet the following
requirements:
•
Figure 1. With Presenter view, what you see on your screen while you are giving the
It must have multiple monitor
presentation
capability. Most modern laptops
have this capability built in.
2. Turn on Presenter view:
• It must be running an operating system that supports
a. In PowerPoint, select Slide Show > Set Up Slide
multiple displays, such as Windows XP or later.
Show.
1. Enable multiple monitor support.
b. Under Multiple monitors, select the Show
Set the display options:
Presenter View check box.
a. In Control Panel, click the Display icon.
c. In the Display slide show on the list, click
b. Choose the Settings tab in Display Properties
the monitor you want the slide show presentation
dialog.
to appear on.
c. Turn on Primary and Secondary monitors.
You can have your speaker notes, narrative and prompts
d. In some later versions of Windows, you also have
visible to you on your laptop, while the audience only
the option to Connect to a projector.
sees the slides on the projector. The screen capture in
If you have this option, select it and then select
Figure 1 shows what you typically see while you are
Extend as shown in Figure 2.
giving the presentation. Also, you can fiddle about on the
laptop getting organised, and
the audience won’t see
anything until you start the
slide show.
This is a great tool!
Figure 2. Setting up your computer

Southern Communicator

Transcription

Similar documents

oc pepper spray certification course

IACCA 2016 Brochure April 2016

Certificate of Registration

Petal Recognition - International Living Future Institute

matthias kolowrat

certificate - Dietze + Schell

FM-Web

Various Carbuilders EC Certification in Accordance with TSI CR

SUSTAINABLE PACIFIC GROVE APRIL MEETING

Klinitrial provide gold standard training and certification of sites and

How to Develop an Employee Communications Department A Guidebook