Communicator Autumn 2014

Transcription

Where are technical communicators?
Finding the location of your colleagues
Communicator
The Institute of Scientific and Technical Communicators
Autumn 2014
Breaking into technical
marketing communications
Learning how to get
accurate reviews
Improving your
verbal skills
Why publishing needs
technical communicators
Translation of technical documentation
Do you need to:
translate your technical documentation on time, within budget and with total confidence?
optimise your source text for translation?
seamlessly integrate your technical authoring with translation processes?
precisely replicate the high standard of your source documentation?
achieve a solution tailored to your specific requirements?
If so, then contact ITR today to discuss your projects!
ITR specialises in translating and localizing technical content. This includes documentation, software applications, user
assistance, websites and eLearning content. Whatever your authoring environment, technical domain or languages
required, ITR has the linguistic resources and technical expertise to meet your needs.
Key features and benefits of our technical documentation translation services:
Streamlined workflows that integrate with your preferred authoring environment – to optimise re-use
Expert use of all industry-standard DTP and graphics tools – for compatibility with your authoring environment
Protection of your source text structure throughout the translation cycle – for accuracy and productivity
Expert use of industry-standard and ITR-developed translation tools – for consistency, efficiency and cost benefits to you
Expertise in single-sourcing workflows – to optimise content re-use
Quality assurance – to ensure end-user acceptance
A clear, consistent and structured approach to every project we manage – for your peace of mind and brand integrity.
To discover how our services could benefit your business, contact us today.
ITR International Translation Resources Ltd.
4 Dolphin Square Edensor Road London W4 2ST
T: 020 8987 8000
[email protected]
www.itr.co.uk
3
ISTC news
Communicator The quarterly journal of the ISTC
ISSN 0953-3699
Production team
Commissioning Editor
Katherine Judge, [email protected]
Book review co-ordinator
Linda Robins, [email protected]
Copyeditors
Tony Eyre and Nick Robson
Proofreaders
Tim Joynson, Linda Robins and Jean Rollinson
4
5
6
7
8
9
10
14
From the editor
Area groups
President’s view
ISTC directory
Online groups
Continuous professional development
Event news
Industry news
Articles
Where are all the technical communicators?
16
Ellis Pratt
Locating technical communicators
18
The e-book explosion
22
Roughing it out with reviewers
24
The ever-changing face of content
www.istc.org.uk/our-publications/communicator/
subscribe-to-communicator
27
A hybrid approach to XML conversion
Submissions
Guidelines
32
Laying the foundations for change
35
Breaking into technical marketing
38
Advancing technical communication
42
Training in verbal skills
44
Facilitate towards agreement
48
A tool that even your developers will use
52
Scroll add-ons for Confluence
56
SideKick – every author’s assistant
Layout
Greenhouse Graphics,
www.greenhousegraphics.co.uk
Advertising
Felicity Davie, [email protected]
Letters
[email protected]
Subscriptions
www.istc.org.uk/our-publications/communicator
Deadlines
Spring
Summer
Autumn
Winter
copy by
published
copy by
published
copy by
published
copy by
published
31 January
21 March
30 April
21 June
31 July
21 September
31 October
21 December
Back issues
www.istc.org.uk/our-publications/communicator/
archive-of-back-issues (ISTC members only)
The Editor welcomes articles and letters for publication.
Opinions expressed by contributors are not necessarily
those of the ISTC. All articles are copyright and are the
property of the authors, who have asserted their moral
rights. For permission to reproduce an article, contact
the author directly or through the Editor. All trademarks
are the property of their registered owners whether
indicated or not. Advertisements are accepted on the
understanding that they conform to the British Code of
Advertising Practice. Acceptance of an advertisement for
publication does not imply that a product or service has
the ISTC’s endorsement.
The Institute of Scientific and
Technical Communicators (ISTC)
Airport House, Purley Way, Croydon, CR0 0XZ
T: +44 (0) 20 8253 4506
E: [email protected]
F: +44 (0) 20 8253 4510 W: www.istc.org.uk
Printed on recycled paper using vegetable inks and
low volatile organic compound (VOC) chemistry.
Toni Ressaire
Explaining why the publishing industry needs technical
communicators
Geetha Haridas
Ensuring your documentation is accurate by using reviewers
Louise Law
Discussing how global content strategies are changing
Maxwell Hoffmann
Converting documentation to XML
Andrew Joly and Kayleigh Tanner
Creating a learning and communications architecture
Cheryl Landes
Sharing strategies for improvement by applying customer
experience principles
Michelle Despres
The demand is high and so is the pay: describing more about
technical marketing communications
Jean-Paul Bardez
Looking at improving your verbal communication skills
John Crawley and John Burns
Using mediation as a vital tool in the manager’s kit bag
Raymond Gillespie
Considering lightweight markup languages
Nils Bier
Reviewing Confluence and the add-ons available
Carsten Regehly
Appraising the latest software development from Ovidius
Regular columns
59
60
62
63
64
66
cover
MadCap tips – Matthew Ellison
Ethical dilemmas – Warren Singer
Adobe tips – Colum McAndrew
Editing – Jean Rollinson
Book review – Andrew Peck
Reflections – Andrew Peck
Recipe cards © Antti Hietala 2014
Recipes are copyright Skandinavisk Press AB. These recipes
are reproduced with kind permission from IMP AB.
4
ISTC news
From the editor
The Autumn issue is the issue that’s
read at Technical Communication UK
(TCUK), the conference hosted by the
ISTC. Have you been to the conference?
It’s an excellent place for learning about
technical communication, networking
and sharing your ideas, suggestions and
grudges with those who understand
your everyday work issues. If I don’t
see you at TCUK 2014 (Brighton 16–18
September) I hope you do manage to
attend another technical communication
conference or TCUK next year. There’s
always something new to learn.
In this issue
Have you ever wondered how many
technical communicators there are
or where they’re based? Ellis Pratt at
Cherryleaf, together with the ISTC, has
put together location data based on
survey information.
If you have worked with customers,
you could apply customer experience
principles in technical communication.
Michelle Despres has more on this. Her
article looks at customer journeys. This
immediately had me thinking about user
stories in agile development. There are
some similarities, although user stories
are mostly used in the design and
development phases and are focused on
a product, whereas customer journeys
illustrate the current state, ensuring that
the experience needs to be good.
Your skills are transferable and
could be used outside of technical
communication. Toni Ressaire
explains how the publishing industry
needs us and Cheryl Landes explains
how to get into Technical Marketing
Communications. In fact, if you’re
really interested in technical marketing
communications, there is an opening in
the ISTC to become a volunteer and help
advertise the ISTC. Send an email to the
office, [email protected] if this sounds
like something you would be interested
in doing.
To create better documentation,
Geetha Haridas discusses how to get the
most out of your reviewers and JeanPaul Bardez explains how to improve
your verbal skills when dealing with
colleagues and customers. And, if you
work in a global environment, Louise
Law helps you create a global content
strategy.
If you’re interested in creating training
and learning material, then you need
to read Andrew Joly and Kayleigh
Tanner’s article about learning and
communications architecture.
If you’re thinking of using new
software, there are reviews of Scroll
add-ons for Confluence, SideKick
from Ovidius and Markdown. Maxwell
Hoffmann follows on from his XML
article in the Summer issue.
John Burns is back collaborating with
John Crawley on mediation.
APEX Award 2014
Communicator has won an award for the
fifth year in a row. Congratulations to
everyone involved in the publication.
…And finally
Are you reading this article on the train?
At home? At work? At TCUK? Or another
conference? Is a paper format the best
format for Communicator or would you
prefer an online version or more
frequent issues? If you have any
preferences, do get in touch as we’re
thinking of how to take Communciator
forwards. C
What topics would you like to see?
Do you think that some technical
communication topics are not covered
in enough depth in Communicator? If
you have any feedback (good or bad),
or suggestions for potential articles,
please email [email protected]
Katherine Judge FISTC
Tw: @ISTC_Journal
GRAPHIC COMMUNICATIONS
FOR A SUSTAINABLE AND DIGITAL WORLD
01256 880770
GREENHOUSEGRAPHICS.CO.UK
Design | Print | Direct Mail | Marketing Consultancy | Exhibition | Display | Signage | Wall Coverings | Vehicle Graphics
Scan to
see what
we can do
for you.
5
Area groups
The ISTC area groups offer an opportunity for technical communicators to network and share knowledge and expertise. The groups are
open to everyone from all industries in the local area (you don’t even need to be an ISTC member to attend), and it’s free. The groups
meet at intervals during the year and hold talks, peer discussions, demonstrations and social evenings.
Interest groups give you an opportunity to meet people in your industry. For more information, please contact the relevant organiser.
Interested in attending?
North East England
Ireland
If you’re interested in attending or you’d
like more information, please contact the
local organiser or the ISTC Office
[email protected]
Organiser: Janine Weightman
ISTC Irish Group
Interested in setting up a group?
If you’d like to set up a group in your
regional area or for a specific area of
interest, please contact:
Tom Dumic, Area Groups Manager,
LinkedIn (LI) groups
North West England
Organiser: David Jones
LI sub group: ISTC NW Area Group
Southern
Organiser: Marjorie Jones
LI sub group: Southern Area Group
Some of the area groups have their own
groups on LinkedIn. Other groups are sub
groups of the Institute of Scientific and
Technical Communicators group.
Thames Valley
England
Cambridge
Yorkshire
Organisers: Derek Cooper, Jeff Bronks
LI: Cambridge Technical Communicators
London
Organiser: Darren Mitcham
LI sub group: Thames Valley Area Group
Organiser: Coordinator wanted
East of Scotland
Organiser: George Lewis
Midlands
West of Scotland
Organiser: Katja McLaughlin
LI sub group: West of Scotland Area Group
2XUH[SHULHQFHGWHDPVZRUNZLWKWHFKQLFDODXWKRUV
LQPDMRUFRPSDQLHVZRUOGZLGHSURYLGLQJDUHOLDEOH
SURIHVVLRQDOODQJXDJHVHUYLFHLQDOOGLVFLSOLQHV
Irish Technical Writers – an ISTC area group
Organisers: Patrice Fanning,
Yvonne Cleary, Bridget Walsh
LI: Irish Technical Writers--An ISTC
Area Group
Wales
South Wales
Organiser: John Espirian
LI sub group: South Wales Group
Interest groups
Oil & Gas
Scotland
Organiser: Claire Hooper
Organiser: John Burns
LI sub group: ISTC Midlands Area Group
Organiser: Adrian Rush
Organiser: Chris Knowles
LI sub group: ISTC Oil and Gas
MadCap
Organisers: Marjorie Jones, Tom Brindley,
Kai Weber
LI: MadCap UK & Europe Users Group
:H·UHWDONLQJ
\RXUODQJXDJH
7UDQVODWLRQPDQXDOVSDWHQWVGRFXPHQWDWLRQ
3XEOLVKLQJ\RXUSUHIHUUHGDSSOLFDWLRQ
/RFDOLVDWLRQVRIWZDUHPDUNHWLQJLQIRUPDWLRQ
*OREDOLVDWLRQ\RXUZHESUHVHQFH
19-19A ST ANDREWS ROAD | BEDFORD | MK40 2LL
01234 271555 | :::%(')25'75$16&28.
6
ISTC news
President’sview
A little perspective
As I retire as ISTC President, I thought
I would take the opportunity to share
my professional journey and how my
perspective of the ISTC has developed as
my involvement has changed over
20 years, and as the ISTC has evolved.
The view from the outside
I first became aware of the ISTC shortly
after I became aware that Technical
Authoring existed as a job. We are
talking 1994 and I had just joined TMS
Computer Authors Ltd in Godalming.
I was taken on to sell technical
documentation projects and some of
my colleagues were ISTC members.
As the projects team struggled, I was
moved to the booming agency team and
within months realised I had found a
world where I could thrive. I spoke to
hundreds of companies and hundreds
of technical authors – and enjoyed it.
I was vaguely aware of the ISTC as a
professional body, but membership of
the ISTC certainly didn’t figure as an
important criterion for customers.
The view from the fringe
I started to attend the annual ISTC
Conference (I think in Windsor in 1995).
As a salesman, I used the opportunity
to meet some of the people I had only
spoken to on the phone. I remember
feeling rather isolated and exposed,
and for the next few years of attending
the conference, the focus was on
the bunch of TMS sales people not
getting too drunk on the Friday night
so that they could still function the
next morning. I am sure I must have
attended sessions and learnt something
but I have no idea what. I was aware
of the rivalry between TMS and the
other services companies such as
Kudos, Plain Words and AST. At those
late 90’s conferences, it did seem to
be a professional community that
was thriving – although I remember
individual authors still complained
about themselves and their profession
being undervalued just as some do
today…in fact I am sure some of them
are the same people.
By 2001, I was starting to meet
authors in other countries, and
attending Society for Technical
Communicators (STC) Chapter meetings
in Europe. With that experience, the
ISTC conferences and the atmosphere
within the UK profession started to look
insular and despondent. My perspective
had changed.
The view from the inside
When I set up 3di in 2002, my
perspective changed again. I needed
to build a business, and that was going
to rely on being able to find customers,
and resources. I was also going to
need to become far more expert in my
chosen field than I had needed to be up
to then. The ISTC was a good place to
start. I joined as an Associate member,
and then became a Member a year or
so later. I started writing articles for
and advertising in Communicator and
InfoPlus+ and continued attending the
Conference. I learned to appreciate
the professional development
opportunities and encouraged (and
for a time even paid for) 3di contract
authors to join the ISTC.
The view from the centre
The more I learnt about the profession
I was part of and depended on, and the
markets in which it operated the more I
realised that the ISTC had the potential
to do much more to support and help
that profession thrive. I started to help
with the Marketing and joined Council
in 2004.
My investment of time, energy and
money in the ISTC started to pay
dividends. I won projects I would never
have been aware of, and I worked with
technical authors I would never have
known. And I learnt new skills: being
interviewed about industry salaries
for Reader’s Digest, taking part in a
discussion about instruction manuals
for BBC Radio 4. Giving presentations
and writing articles. Recognising and
applying my relative professional
strengths and collaborating with
others to learn from theirs.
The view looking out
For me, the opportunity for professional
collaboration has been the key benefit of
being part of the ISTC. It’s collaboration
that enabled the new Technical
Communication UK conference to turn
from an idea into a reality.
Although benevolent dictatorship
has its advantages when you run your
own company, it simply doesn’t work
in a volunteer-based professional body
that has to sustain itself and thrive as
volunteers come and go. You need to
pool your energies and agree shared
goals. Those in the centre need to
look out towards the membership
and beyond, to the wider profession
and the markets they serve. With that
perspective, those in the centre can
work steadily and sustainably to meet
their needs.
From my perspective, I think all
of us who have worked on the inside
and at the centre of the ISTC in recent
years can be immensely proud of
what we have achieved so far, a few
highlights being:
a new, thriving conference
a journal of consistently rich and
useful content
new mentor and CPD programmes
new local area groups and support
framework
new user and industry groups
a coherent brand and better marketing
assets
regular surveys
a trusted and efficient admin and
project support team
an open, team-based, sustainable
governance structure
a talented and growing network of
volunteers
What’s your perspective?
You may well see a different ISTC to me.
My journey has been my own and will
continue to provide me with different
perspectives as my volunteer role
changes and I start to move away from
the centre.
It’s been a privilege to serve as ISTC
President for the last four years and I am
looking forward to continuing on the
Council team and collaborating with
Alison Peck, your new ISTC President. C
Bonetta, L (2011) ‘The best words in the best order’
Nature, Vol 475: 255–257
www.nature.com/naturejobs/2011/110714/pdf/nj7355255a.pdf (accessed August 2014)
Paul Ballard FISTC
7
Your ISTC directory
The Institute of Scientific and Technical Communicators (ISTC) is the largest UK body for people engaged in technical communication. The ISTC
encourages professional development and standards, provides research resources and networking opportunities, and promotes technical
communication as a profession.
To join the ISTC, change your grade, or get involved in what we do, contact the ISTC office on +44 (0) 20 8253 4506 or [email protected]
(The symbol * indicates a member of the ISTC Council)
President
Paul Ballard * (until 2014 AGM)
Alison Peck * (from 2014 AGM)
[email protected]
Treasurer
Peter Fountain *
[email protected]
Administration
Elaine Cole
[email protected]
Communicator
Katherine Judge *
[email protected]
@ISTC_Journal
Community
Area groups manager
Area groups
Surveys
InfoPlus+ Editor
Events
Forums
Andrew Marlow *
Tom Dumic
Elaine Cole
Emma Bayne *
Andrew Marlow *
Diana Logan
Elaine Cole
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
International
Edward King *
[email protected]
Membership
Linda Robins *
Iain Wright *
[email protected]
[email protected]
Other Council Member
Paul Ballard * (from 2014 AGM)
Professional development and recognition
Education and Continuous Professional
Alison Peck * (until 2014 AGM)
Development
David Farbey * (from 2014 AGM)
Education Administrator
Mentoring
Linda Robins *
UK Technical Communication Awards
Galyna Key *
Careers
Alison Peck *
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
Resources
ISTC History
Resources
Linda Robins *
Emma Bayne *
Amanda Atkin *
[email protected]
[email protected]
[email protected]
Technical Communication UK conference
David Farbey * (until 2014 AGM)
Colum McAndrew *
[email protected]
@tcuk_conf
Twitter@ISTC_org
Website
Gordon McLean
ISTC news
[email protected]
And the winner is…
The Summer
2014 issue of
Communicator
had a
photography
competition
encouraging entries from photographers
who had taken a picture of something
related to technical communication. The
entries ranged from photos of recipe
cards, to mugs, car parking meters,
conferences and more.
Recipe cards
The winner writes: “These recipe cards
were popular in the 70s and 80s in
Scandinavia.
Each card has a picture of a dish on
one side and the list of ingredients and
cooking instructions on the other. You
got them in the mail a few cards at a
time. Many families collected them.
In the photo are my mom’s cards in
Finland.
The cards are a brilliant example of
communicating condensed information.
Colourful, brief and to the point. The
glossy surface can be wiped with a wet
cloth so they are also designed for the
point of use.
I was inspired by the cards recently
when I wrote app design guidelines. I
looked for a format that is a joy to read.
The core message of each guideline
such as “Be a good tablet citizen” had
to be memorable even if the reader had
little time.
My guideline cards are a success
online but I had even more fun printing
them for my company’s annual
developer conference. I printed them in
accordions like holiday postcards with
perforated tear-off edges. The attendees
loved them. Since then I have noticed
many mobile-first interfaces using the
card model.”
And the winner is: Anntti Hietala.
Thank you to all of you that entered, in
particular for the photos from David
Barber and Diana Logan. C
Katherine Judge FISTC
8
ISTC news
Online groups
Mike Unwalla summarises recent discussions.
http://finance.groups.yahoo.com/group/ISTC_Discussion – general discussion forum for members of the ISTC
http://finance.groups.yahoo.com/group/ISTC_IASIG - independent authors’ special interest group forum for members of the ISTC
Promoting technical communication
The message ‘Promoting awareness of
Technical Communicators’ started a
very long discussion. Some members
think that the ISTC does not promote
technical communication sufficiently.
Rachel Potts is a member of the
ISTC Council, and she replied to the
comments.
Each year, Council members look at
a list of all the things that the Council
wants to do. That list comes from
members through conversations,
surveys, emails messages to the ISTC,
and comments in the online groups.
Also, Council looks at what other
organisations do. Council creates a
shorter list of items that fit with the
direction for the ISTC and what Council
thinks is possible with the resources
available (skills, people, money).
During Rachel’s 6 years on Council,
ISTC did many things, but it did not
do everything that it wanted to do.
However, “members tell us about
getting a job via an area group, getting
help with projects through this
discussion list, feeling proud of giving
their first ever presentation at TCUK,
and appreciating the help of a mentor
during their first steps in their tech
communication career.”
ISTC receives questions about
technical communication as a career
or as an area of expertise from many
people and organisations. Examples
are universities, Nature magazine, and
the BBC. Many recruitment agencies
and employers use the online groups
to advertise jobs. The requests for
collaboration that ISTC gets from other
organisations, and the contributors, the
sponsors, and the advertisers for TCUK
and for Communicator show the respect
that people have for the things that the
ISTC does.
What will you do to help the ISTC
achieve the things that you think are
important?
Issue numbers in URLs
A member is developing a content
management system (CMS) that will
supply PDF manuals on a website. He
must decide whether the URLs contain
issue numbers. He wants to know the
advantages and the disadvantages of
these options:
If the URLs do not have issue
numbers, the customer can only
download the latest issue, which is
the best option for new visitors.
If the URLs have issue numbers, the
CMS will supply the latest issue.
However, people can ‘hack’ the URL to
get an earlier issue. (Possibly, the CMS
can index the earlier issues.)
Members gave this advice:
If customers want old issues, give
them the option. Do not make them
‘hack’ the URL.
Use evidence to decide which
documents the customers need. Find
a technical solution for that need.
Location of technical communicators
‘Tech Comm on a Map’ shows the
location of conferences, societies, and
businesses that are related to technical
communication
(http://sarahmaddox.github.io/
techcomm-map/).
The map inspired Ellis Pratt to
develop the ‘Cherryleaf Survey –
Location of Technical Authors map’ for
technical communicators who are in the
UK. If you are a technical communicator
in the UK, add your location to the map
(www.cherryleaf.com/useful-resources/
cherryleaf-survey-2014).
Technical reviews
An editor of instruction manuals
wrote that when engineers review
documents, they “…demand editorial
changes based on their personal
preferences… the changes sometimes
conflict with the house style, other
engineering review comments and
eventually customer comments.”
How do members help engineers
to restrict their comments to only
technical information?
Members suggested these things:
Be as clear as possible about what you
want the engineers to do.
Tell reviewers to restrict their
feedback to technical information
only, because the document will
be reviewed for English and
formatting later.
Tell the engineers that the
formatting is not completed. Thus,
they can ignore problems with
formatting.
Supply a checklist for reviewers and
show who is responsible for what.
Put a large red box at the top of the
document that contains a bulleted list
of what to review and what to ignore.
Tell the engineers that if they review
only the technical content, they
decrease the time for their review.
Put the content into a new document
that has no formatting.
Ask the engineers questions. Instead
of “please review the technical
content only,” ask “does this section
accurately reflect the hardware?”
Ignore comments that do not agree
with the style guide or with good
English. Usually, reviewers do not
make sure that their comments and
‘corrections’ have been used. C
How to join the online groups
ISTC_Discussion
Send an email to Elaine Cole,
[email protected]
with a subject line of
‘ISTC_Discussion subscription’
and include your name and
ISTC membership number.
ISTC_IASIG
Send an email to Alison Peck
[email protected]
with a subject line of
‘ISTC_IASIG subscription’
and include your name and
ISTC membership number.
References
Bonetta L (2011) ‘The best words in the
best order’ Nature, vol 475, 255–257
www.nature.com/
naturejobs/2011/110714/pdf/
nj7355-255a.pdf (accessed August 2014)
Mike Unwalla FISTC
9
A learning journey
As the ISTC’s CPD policy enters the second half of its first year,
Alison Peck looks back at the journey that brought us to this point.
Implementing a Continuous Professional
Development (CPD) policy for the ISTC
has been a learning experience in itself,
both for the ISTC Council and for our
membership. This means we’re fairly
relaxed about what we’re expecting to
see from those Fellows we ask to submit
their CPD records for review. We also
want to encourage Members to start
creating their CPD records now, as they
may provide support for an application
to upgrade to Fellow.
The first thing to stress is that you
have total control over your CPD
records: you own them, others only see
what you choose to share, and anything
you share for review purposes remains
confidential. You also don’t need to
provide detailed evidence of every bit
of learning you’ve done, just enough
to meet the minimum requirement (at
least 10 points per year and a total of 90
points over three years). You can create
your own notes for other learning, or
containing more detail… but we don’t
need or want to see them. For example,
some of my learning this year involves
clients I can’t name, so they will remain
anonymous. Other learning involves
issues I can’t discuss, so I simply won’t
include them.
If we ask to see your CPD records, we
need to know: what you did, when you
did it, what you learnt, if and how you
intend to apply it, and how many points
you are claiming. (All of these, with
the exception of the number of points,
form your ‘reflection’ on the learning.)
The ‘evidence’ is your reflection: some
activities come with other supporting
evidence, such as certificates of
attendance, but they are not essential.
How you provide the information
is your choice. We’ll accept anything
from a simple table (either in a wordprocessed document or a spreadsheet)
through to videos or podcasts.
Finally, if we don’t ask to see your
record, please don’t send it to us.
We will only be looking at a random,
representative sample.
A personal perspective
As a Fellow of the ISTC myself, I have
a CPD record. Writing this article has
prompted me to review what I’m doing:
what I’m learning and what I’m recording.
For me, the best approach is to make
notes on what I do when or shortly after
I do it (whether ‘it’ is reading an article in
Communicator, investigating a new tool
or sharing techniques with others). I use a
blog to do this; I don’t have to, I just find
it convenient as I can label the entries.
I can also go back and add comments
later, as so much of my learning takes
…others only see what
you choose to share…
place after the event that triggers it. For
example, a discussion with a client about
an issue may lead to some research,
followed by a change in approach to
better meet that client’s needs. Or being
asked to use a new tool encourages
me to revisit the way I have organised
some content because the new tool has
prompted me to think in a different way.
I don’t worry too much about the CPD
points at this stage. I do put the activities
in a spreadsheet so I don’t have to hunt
for them later, but I may not allocate
points until I look back and decide how
much I’ve learnt.
I expect to be providing my CPD
record for review at the end of this year,
even if not randomly selected. After
all, I can’t provide guidance to others if
I’m not doing it myself. Again, for me,
I’ll probably keep the process simple,
providing links to the bits of my blog that
are relevant as reflections and a list of
activities and points.
I’ve made my blog public, but that’s my
personal choice. I do a lot of work with
CPD outside of the ISTC, and it’s easier
to be able to show people what I do than
trying to explain.
What others are doing…
So far in 2014, I’ve represented the ISTC
at two meetings of the CPD Forum (a
group of people from professional bodies
with responsibility for CPD). I spoke
at the most recent one, outlining the
approach the ISTC has taken. People were
very interested, as some of those with
a regulatory requirement are switching
to a more flexible approach that
mirrors our own CPD position. People
work at different levels, in different
environments and have different
learning needs: technical communicators
are not unique in this respect.
Help and guidance
The CPD Framework document has been
on the ISTC website for nearly a year
now. Over the next few months, we will
add some templates, guidance notes
and other information to help you gain
maximum benefit from the process.
Tell us what you think
We’re keen to hear how you’re finding
the CPD process. As I’ve said before, it
should be possible to meet the
requirement without spending any
money or devoting a lot of time to the
process. If that isn’t your experience, we
need to know – otherwise we can’t do
anything about it. C
References
‘CPD Information for Members’
www.istc.org.uk/training-education/
cpd-information-for-members
Peck, A (2013) ‘CPD: why bother?’
Communicator, Spring 2013: 11–13
Peck, A (2014) ‘Your professional
development matters’ Communicator,
Autumn 2013: 14–15
Alison Peck FISTC is the
member of the ISTC Council
with responsibility for
Professional Development
and Recognition. She
manages Clearly Stated Ltd, and is a
technical author in the company.
W: www.clearly-stated.co.uk
B: My CPD reflections:
http://ajplearningjournal.blogspot.co.uk
10
Event news
UA Europe 2014: Trending in Kraków
Galyna Key summarises two amazing days at the UA Europe
conference in Kraków, Park Inn Hotel, 5–6 June.
It was my great privilege to represent the
ISTC at UA Europe 2014. This is an annual
conference geared towards technical
communication professionals with an
interest in software user assistance and
online Help. As the title implies, the
conference is international in nature; last
year it was hosted in Manchester, UK.
This year the delegates from 19 countries
made their way to the welcoming city of
Kraków, Poland.
The sessions were divided into two
tracks, with a key focus on mobile user
assistance, and responsive web design.
If you are thinking that two days, 19
speakers, and 28 presentations makes
for a rather intense experience, you are
not wrong. Except that there were plenty
of refreshment breaks giving us time to
catch our breath, socialise, and to visit
the stands of the conference exhibitors
and sponsors. 10/10
conference continued in two streams
And I needed to figure out how to split
my time between manning the ISTC
exhibition stand in the hall, and attending
the sessions.
If you were there with me, you could ‘go
all techy’ and dip your toes into HTML5/
CSS3 coding, closely scrutinise the ‘nuts
and bolts’ of embedded help, get ‘the vibe’
of XSL-T, and build a semantic search
solution. Or you could choose more
Indulging an inner geek
The conference attracted superb speakers
from around the world. Joe Welinske, Dr
Tony Self, Jang F.M. Graat, Ray Gallon,
Dave Gash, Dr Chris Atherton, Karen
Mardahl, Matthew Ellison – to name but a
few. It was great to rub shoulders with so
many thought leaders in our industry.
City of Kraków welcomes us with the
beautiful blue skies
Pawel Kowaluk shows how to create a
semantic search solution
Location, location, location
Park Inn Hotel was an impressive choice
for a venue, boasting great facilities,
friendly staff, lots of delicious food, all
within walking distance of the historic
town centre. The Wi-Fi speed was decent,
although it took some figuring out how
to connect, and then it kept dropping out.
9/10
Intensely does it
The conference organisers left nothing to
chance, and handcrafted a tightly packed
programme reflecting the latest industry
trends, technical developments, and best
practices in software user assistance.
Delegates exchange ideas and
inspirations during a session break
Matthew Ellison is getting ready for his
opening speech
It is hardly surprising my inner geek
was spoilt for choice, for this was a
conference to cater for all tastes, mine
included. The first day began with a
warm welcome from Matthew Ellison,
followed by two keynote presentations.
Joe Welinske bravely held a mirror
to the UA practitioners in the States,
and reviewed the results of the 2014
WritersUA Survey. It turns out there
is a growing demand for Agile and
DITA savvy technical communicators,
especially when two big industry players,
Microsoft and Amazon, are finally
embracing DITA. The next keynote
speech by Dr Tony Self explained, once
and for all, the difference between the
adoptive and responsive web design
techniques. I have to say, I’m now a huge
proponent of responsive web design. With
the keynote presentations delivered, the
conceptual topics, and get to know your
users, design user transactions, rethink
documentation with DITA, evaluate
trends in mobile user assistance, see
agile documentation in practice, learn
to get things done – and so much more.
The conference closed with a thought
provoking discussion on topic length and
granularity by Matthew Ellison. 10/10
Fun and games
Our name badges were encoded with a
couple of strange symbols, not unlike
kill marks on WW2 aircraft. We later
discovered that a pre-conference
questionnaire was turned into a musical
quiz, and the music bands represented
our areas of professional interest. Our
challenge was to talk to others, and
to figure out which country the band
represented, and which area of interest.
This lovely icebreaker really helped in
striking up conversations with others, and
was lots of fun to decipher.
Other highlights included themed lunch
tables – to keep the conversations flowing;
evening drinks reception, trivia quiz, and
an impromptu birthday party at a Kraków
restaurant. 10/10
(And yes, winning the trivia quiz with my
11
soap!
Fresh air in the branch
Delegates are having fun with the
musical quiz
team might have influenced my score ever
so slightly.)
With hashtags at the ready
If you run a search for #UAeurope
(https://twitter.com/hashtag/uaeurope),
you can read the conference story
narrated by the likeminded twitterati
and myself – just as the events were
unfolding.
Onwards
UA Europe 2015 is rumoured to be the
10th anniversary conference, and is
definitely the one to watch out for. C
DIARY DATE
UA Europe 2015
4–5 June 2015
Southampton, UK
www.uaeurope.com
Galyna Key MA, FISTC
is firmly convinced that
technical communication is
the coolest and most creative
discipline out there. Over the
years, she stopped trying to figure out whether
she is a project manager, product manager,
engineer, designer, tester, localisation expert, or
a knowledge architect and decided to have fun
changing her hats on a regular basis. She is
currently leading the transformation of
customer learning experience (LX) at Datix. In
her spare time, she manages an annual UKTC
Awards programme as part of her volunteer
service on the ISTC Council.
Tw: @galynakey
What is soap? It’s
a conference and
a community that
gathers people
from Eastern
Europe around
technical communication. It fills a
niche that has existed on the local
scene ever since the beginning of
technical communications in Poland.
Our aim is to create a meeting place
for all people involved in content
development. We want to show that
our day-to-day work matters and
brings value to the organisation, that
well-prepared content is an asset
and not just a basic requirement.
We want to create a sense of
community and provide technical
communication professionals with
an opportunity to grow, exchange
ideas and experiences, and above all,
to network.
We kicked off in June 2013.
Inspired by Congility 2013, we said:
“Let’s organise a conference”. By
mid-June of that year we had a name
and started looking for speakers and
sponsors. The feedback far exceeded
our expectations. On October 3rd,
around 120 people joined us at the
first soap! conference ever.
From that moment on, we have
evolved considerably. We started
organising webinars and local
meetings. We decided to make soap!
2014 a two-day event with some big
names on the speakers’ list. Our
goal is to bring together, not only
technical communicators
professionals and students, but also
business managers, company
owners, start-ups, project managers,
investors, coaches, and many others.
We want people to share their
insights and expectations. We want
to create an “ecosystem” in which all
of the above-mentioned
professionals understand each
other’s perspective, in which we can
work together to achieve the
ultimate goal of providing highquality content. Does it sound like a
place for you? Join us this Autumn
in Kraków. Become a part of soap!
and help us make the difference! C
DIARY DATE
soap!
2–3 October 2014
Hub:raum, Przemysłowa Street 12,
Kraków, Poland
soapconf.com
Agnieszka Tkaczyk
supports soap! She is an
information developer at
IBM and a freelance
translator.
Gosia Radymiak is one of
the founders of soap! She is
a technical writer and
quality specialist at
Motorola Solutions Inc.
12
Event news
Localization World Dublin 2014 Member news
Record number of attendees attended this conference
in Ireland. Katie Botkin summarises the event.
New Members
Member
Dinner entertainment
Localization World Dublin 2014 was held
on June 4–6 in the futuristic Convention
Centre Dublin on the River Liffey, and
drew a record number of attendees
— 638 in total — many of them from
Ireland’s booming localization sector.
The conference covered nine tracks,
from Localization Core Competencies to
Content Strategies to the relatively new
Unconference, which provided a more
free-form environment for participants
to choose their own localization topics
to discuss.
The June 5 keynote address given by
Swedish futurologist Magnus Lindkvist
followed the conference theme of
disruptive innovation. “Success is
possibly one of the most dangerous
forces to unleash in an organization,”
said Lindkvist, “because it often makes
companies complacent and entitled. The
amateurs inherit the earth, because they
don’t go in with legacy thinking.”
Lindkvist went on to explain that true
innovators are often considered odd
in their own era and even threatening,
because they tend to eventually render
the competition obsolete. “Do you want
to compete and make friends and be
on the cover of Forbes magazine, or do
you want to create, and make enemies?”
Lindkvist asked, adding jokingly
that “you can only do both if you’re
consensus-seeking, boring and Swedish.”
If you want to create and innovate, said
Lindkvist, you should do four things.
First, look for secrets, “for ideas among
the silly, the strange, the weird.” Second,
play with the recipe and experiment.
“Experimentation is creation,” said
Lindkvist. Third, recycle failures. Fourth,
and related to recycling, be patient and
persistent: think long-term, because
“anything can look like a failure in the
middle.”
New to the Dublin conference was
a consultants’ microtalk, a one-hour
discussion resulting from the first
consultant workshop and roundtable
at Localization World the day before.
Aki Ito, Henk Boxma, Gary Lefman
and Adam Blau, all of whom own their
own consulting businesses, ended up
having an engaged discussion about the
rise of localization consultants and the
different niches possible within the field.
Similarly, there was a panel on
attracting, training and retaining
localization professionals based on
a pre-conference workshop on the
same topic. The discussion of the
former included the idea of heightened
collaboration between universities
and businesses, with internships and
training provided to jump-start students’
careers. Speakers for the pre-conference
session June 4, as well as the larger
main conference panel June 5, included
David James of Adaptive Globalization,
Rain Lau of Google, Teresa Marshall
of salesforce.com, Andre Pellet of
ManpowerGroup Solutions and Karl Kelly
of the University of Limerick.
The keynote panel on June 6 followed
business practices and how to adapt
and thrive in times of change. “If your
business model is just to sell large
volumes, maybe you should change
your business model,” noted Monika
Popiołek of MAart Agency Ltd. Olga
Blasco of Welocalize, Suzanne Sowinska
of Microsoft and Doug Strock of Global
Language Translations and Consulting
also spoke on the panel.
The conference dinner on June 5 was
held at Taylors Three Rock, a large pub
outside the city that hosted an evening of
Irish dancing and traditional Irish music.
Additional networking took place at the
opening reception on June 4 and
throughout the conference in the
conference hall, over lunch and
during breaks. C
Katie Botkin is the
managing editor of
Mutlilingual magazine,
which publishes articles on
language, language
technology and the broader business of
how people communicate across cultures.
Susan Armstrong Essex
David Barnes Suffolk
Thomas Bird Holywell
Kate Blackham Milton Keynes
Simon Blight Staffordshire
Dr Kathryn Booth Bolton
Carla Buonacucina Edinburgh
Alistair Christie Oxford
Andy Cowgill Gloucestershire
Suzanne Evans Gloucestershire
Stephen Fanning Bolton
Steve Harding Reading
Lesley Hawken Stamford
Margaretha Hopman Netherlands
Ruth Howard Nottinghamshire
Anna Hutchinson Dublin
Shona Isbister Belfast
Sylfest Muldal Oxford
Alistair Murphy Huddersfield
Erik Stedman Northumberland
Lisa Whincup Ilkley
Gavin Williams High Wycombe
Junior
Chris Brown Graeme Dempsey David Gardiner Mike Hewitt Ian Hutton Andrew Jones Gary Lupson John McGovern Duncan Smith Elizabeth Stewart John McGovern Nottinghamshire
Dorset
Australia
County Down
Dorset
Oxfordshire
Norfolk
Clydebank
Surrey
Derbyshire
Clydebank
Student
Jenny Edwards Aberdeenshire
Transfers
Fellow
Steven Foster Helen Harbord Rowan Shaw Mickleover
Tunbridge Wells
Germany
Member
Andrew Peck Nottingham
Rejoiners
Member
Anthony Graver Graham Stone David Tayler Hertfordshire
Berkshire
Wiltshire
Event news
Congility 2014: serendipity?
Ant Davey reviews the Congility 2014 conference, co-organised by
Mekon Ltd and Urbina Consulting and held in Crawley, UK on 19–22 June.
Is it just me, or do you find to that every
conference you go to has lots of stuff
that’s immediately relevant to what
you’re doing at work?
Congility 2014 delivered thoughtprovoking content for me. I work in
a not-for-profit company populated
with SMEs (subject matter experts)
who develop information for the rail
industry. We are going through a big
change at work. It’s a good change, where
communication, including the technical
variety, will pervade everything we do.
It will become the mainstay of project
planning, rather than the bolt-on activity
it has been seen as before.
As part of that change I find myself
charged with writing the company’s
content strategy and co-writing the
digital strategy. Who’d have thought it?
But we, as technical communicators,
have known for years what it takes to be
able to deliver content suitable for multichannel delivery. Now the management
has caught on to the need to do it, we
have to step out of our introverted
comfort zones and start telling others
that we have the knowledge.
Or at least, we have some of it. Perhaps
strangely, as a ‘technical communicator’
I went to only two sessions in the
technical communication track. And I
had to go to one of them, because I was
presenting it. Having said that, two of
the most popular sessions were ‘how-to’
exposés: on ‘dynamic user assistance’
by Priscilla Buckley, and a report on
some statistical and trend research from
Christopher Ward around becoming
a ‘knowledge broker’ and developing
workflows that make documentation a
revenue generator.
Branding isn’t b*!!*cks
(The presenter’s title for his keynote
speech, not mine!)
Branding: another coincidence?
Part of the change we’re going
through includes a branding review.
But branding is for the marketing
department isn’t it? Not so, according to
keynote speaker Mike Atherton.
‘Branding is what they say about
you when you’re not in the room’, is
the phrase that I, and probably many
others, took away from the informative
and entertaining introduction to
Congility 2014.
So if ‘they’ are saying your
technical documentation is unusable,
unfindable, unreadable, then you are
as responsible for your brand image
as those who develop your products.
Looking at it from the other direction,
your documentation is as important
a part of your brand as the ‘product’
and needs to be treated with the same
value and respect. And it warrants the
appropriate investment.
While we’re talking about keynote
speeches, I must thank Noz Urbina, not
just for coordinating Congility 2014 with
Mekon, but also for educating me on one
point of confusion. Content marketing?
I worked in marketing for the first 15
years of my career, but really didn’t get
it. According to Noz: ‘Content marketing
is marketing by providing good content.
Everything is marketing. Everything is
also user assistance … helping users
make decisions.’ Serendipity again?
Because at RSSB we provide information
to our industry that supports people in
their decision making.
It’s about people
Not just the people for whom we develop
and deliver information, but the people
we work with. The people who are going
to have to change their mindset, their
ways of working. Having attended a
few technical communications events,
I started presenting because there was
so little people-oriented information
available. My first two presentations
were Change management 101, and then
Communication skills 101. At Congility
this year I was impressed to count 13
people-related sessions. Because we, as
technical communicators, know our
current processes, and know what our
processes and workflows will need to
look like, we are in a position to take the
lead or to provide specialist knowledge
and expertise to the inevitable change
that will happen.
It’s also about the other people at the
conference. Congility is an excellent
place for networking and talking to
‘the experts’. They’re human too, and
have been in the place many of us
find ourselves. They’re friendly and
forthcoming. If you didn’t talk to any
of the presenters at (or didn’t even
come to) Congility, you missed out on a
great opportunity.
The breadth of ‘technical
communications’ these days – with
information architecture, information
design, structure, multi-channel
publishing, adaptive and responsive
delivery, video and audio production –
is so big today, that no-one can master
it all.
At some point you will need help from
others. Talking to people, networking,
can show you what you need to know,
who knows what you need to know, and
maybe who you might want to work
with. Congility is a great place to talk. C
Resources
Download slides from Congility:
www.congility.com/congility-2014
Ant Davey MISTC, and
senior member of STC, is the
technical communicator at
RSSB, in London
W: www.rssb.co.uk
T: @antdavey
13
14
Industry news
BOTI
In the second of this two-part series Emma Bayne describes how a new
technical communications organisation developed in Sweden.
Most people with some knowledge of
technical communication organisations
in Europe will have heard of Sweden’s
Föreningen Teknisk Information (FTI)
(The Swedish Association for Technical
Communicators) that was established
in 1964. And for several decades, the
FTI has been the sole organisation
pertaining to technical communication
in Sweden.
However, a few years ago, this
changed as a number of people set
out to add to the Swedish technical
communication organisation
landscape. Today, there are two
Swedish organisations pertaining to
technical communication, the second
one being Bransch-organisationen för
Teknikinformation (BOTI for short,
and meaning the Trade association for
technical communications). Unlike the
FTI association, however, BOTI has no
membership for individuals, but only
accepts businesses and organisations as
members.
From regiment closure...
When two regiments closed during the
first half of the new millenium, and the
Swedish Armed Forces Technical School
(Försvarets tekniska skola) was moved
from Östersund (in the north of Sweden)
to Halmstad (in the southern part of
the country), the town of Östersund
was compensated by an EU project
aiming at making it a centre of technical
communications.
Following a directive, the Swedish
Defence Materiel Administration
(Försvarets Materielverk FMV)
sought collaboration with the Mid
Sweden University and technical
communications businesses in that
sector.
The result was two projects, TIC 1
and TIC 2, which served a number
of purposes relating to technical
communications, such as establishing
strong networks between actors
in technical communications and
identifying technologies and improving
competence pertaining to technical
communication.
Between 2010 and 2013, four
conferences were organised. The
TIC2012 conference showed that there
was a need to engage businesses more
and this was achieved at the conference
the following year by introducing ten
work groups/packages.
When all work packages had been
finalised and the TIC 2 project ended,
the different collaboration partners
decided to form a trade association for
technical communication. In January
2013 Anna Wallinder, Section Manager
of Technical Documentation at ÅF
(a consultancy company) was part
of work package 8, Network building
and establishing a joint company
neutral network, when it was decided
they would form yet another group
with the specific aim of setting up
a trade association for technical
communication.
...to trade association setup
Anna Wallinder, President of BOTI
The work to set up a new trade
association started in January 2013
and the association was set up
and presented at the conference in
November 2013.
In February 2014, the BOTI trade
association had its first annual general
meeting, establishing a Council of which
Anna Wallinder is now the President.
(She took over from Lars Andersson of
TIKAB, who had been acting President
from the setup in November 2013.)
The first AGM also saw the formation
of two new work groups focusing
People involved in establishing BOTI:
Jenny Häggström, KnowIT,
Lars Andersson, TIKAB
Anna Wallinder, ÅF,
Tommy Lundström, Autotech,
Mats Ahnell, Saab,
Roland Behnke, Combitech,
Johanna Vinstersved, Semantix.
on different issues such as the TIC
conference 2014, as well as market
activities and increasing membership
numbers. Eighteen members attended
the AGM, most of whom had recently
joined the association.
According to its vision “BOTI is the
meeting point for businesses and
organisations that develop technical
information in Sweden. Through united
efforts BOTI wants to increase that
status of technical communication in
businesses, organisations and society
as a whole.” In addition, they want to
develop the trade through:
Providing natural logical national
and international meetings points for
sharing competence, future visions
and experiences
Work jointly with marketing of
the trade vis-à-vis businesses,
organisations and future technical
communicators
Drive competence provision issues
Take the initiative and drive efforts
in research related to technical
communication
Contribute to the clarification of
legislation and directives pertaining
to technical communication.
While the ISTC’s definition of technical
communications has always been broad,
BOTI on their website defines technical
communications as “information
regarding technical products, everything
from certain types of marketing material
to post market information” with the
core including “operating instructions,
assembly and installation instructions,
service and maintenance instructions
and post market information such as
spare parts catalogues” adding that “the
boundary vis-à-vis market information
can be subtle although the main rule
is that fact-based information such as
product sheets are to be considered
15
technical communication profession,
influencing public opinion relating
to technical communication and its
benefits, developing standards and a
common conceptual framework. Based
on the rules of the organisation, the
focus of BOTI can be expressed as in
terms of four pillars:
Meeting point
Education
Lobbying
Standards and legislation.
Collaboration partners in the TIC 2
project:
1. The Swedish Defence Materiel
Administration, FMV,
2. The Swedish Armed Forces,
3. Atlas Copco,
4. Scania,
5. Saab (in Östersund and Linköping),
6. Semcon,
7. Combitech (previously Sörman
Information),
8. Autotech,
9. Zert,
10. TIKAB (short for Teknisk Information
i Krokom AB or Technical
Information in Krokom Ltd),
11. Syntell,
12. Teknikkompetens,
13. Corena,
14. Maincon,
15. ÅF (Ångpanneföreningen),
16. Semantix.
the work with the two TIC projects and
the establishment of BOTI was an
important step towards strengthening
the technical communication sector in
Sweden, as well as coordinating efforts
across the board. C
Terminology and resources
BOTI: Bransch-organisationen för
Teknikinformation (the Swedish
Trade association for technical
communications) www.boti.se
ERDF: European Regional Development
Fund
www.gov.uk/browse/business/
funding-debt/european-regionaldevelopment-funding
The future of BOTI and technical
communications
These collaboration partners are either
related to the Swedish Armed Forces
(1–2), technology producers (3–5),
technical communication consultancy
services (6–15) and language services
provider (16).
technical communication while business
folders with sales information are not”.
BOTI aims to become a meeting
point for organisations working with
technical communication through their
website, conferences, their directory of
stakeholders, by offering education, and
courses (both internal and external),
the exchange of experiences, networks,
internal news dissemination, links
to other networks and associations,
education, attracting more people to the
Because BOTI was recently established,
Anna Wallinder says it is difficult to
comment generally on the recruitment
of members, but says the people and
organisations she has spoken to are
positive to a trade association.
There are challenges across the
entire technical communications
chain, according to Anna Wallinder:
everything from educating people
in technical communications and
ensuring the continued influx of
technical communicators, to the
recruitment and getting organisations
to feel confident about hiring junior
staff as well.
As regards the professional side
of technical communications, she
believes the preconditions vary from
organisation to organisation.
“There is an association for technical
communicators [FTI, author’s comment]
and the plan is that we will contact
them and see what common interests
we have” says Anna Wallinder.
There is no doubt in her mind that
FMV: Försvarets Materielverk
(the Swedish Defence Materiel
Administration) www.fmv.se
FTI: Föreningen Teknisk Information
(The Swedish Association for Technical
Communicators
www.teknikinformatoren.se
Mid Sweden University
www.miun.se/en
S1000D Information Resource
www.s1000d.net
SCORM: Shareable Content Object
Reference Model
TIC: Teknisk Information I Centrum
(Technical Information Centre)
Emma Bayne FISTC is a
technical communicator living
and working in Sweden and is
also a member of the ISTC. She
is responsible for the ISTC
history and ISTC surveys.
“ We have been very happy with the service provided
by 3di. They have the know-how, the relevant
experience and the project managers to deliver our
projects and adhere to our high standards
Joseph Nosbuesh, Head of Documentation Management, Roche Diagnostics
Technical Communication
• supply of technical authors
• managed outsourced teams
• information & document design
• modular writing training
• tools & process strategy
• software usability testing
01483 211533
[email protected]
”
Localization & Translation
• software products & online help
• website & e-learning content
• interactive & audio content
• technical & compliance documents
• multi-lingual translation
• scalable localization testing
www.3di-info.com
16
Location
Where are the technical communicators?
The Cherryleaf team has created a survey to find out the location
of technical communicators. Ellis Pratt, explains more.
A post by Sarah Maddox on her ffeathers.wordress.
com blog prompted us to carry out some research into
the geographical spread of technical communicators
around the UK. We’ve found there are places where
technical communication is a veritable hotbed of
activity, but there are places where there are very
ew technical communicators at all.
For those of you that don’t know, Sarah
Maddox is a technical communicator at
Google in Australia. In May 2014, she posted
a series of posts on how you can create
interactive maps using Google’s APIs and
Google Maps1 and she created The Tech Comm
Map2, which shows the locations of technical
communication conferences, societies and
organisations around the world.
For our enquiry, we wanted to create a
map that showed the location of technical
communicators. To collect the data, we created
a form, using Google Forms, and embedded it
in a page on our website
(www.cherryleaf.com/useful-resources/
cherryleaf-survey-2014). It asks a few basic
questions: postcode, your name and email
address (so we could check the integrity of the
data), and then three more detailed questions.
These are people’s gender, their job status
(if they are an employee or a contractor) and
how many years’ experience they have as a
technical communicator.
Behind the scenes
Figure 1. Red shows location of employees, blue pins show
freelancers, and the white pins people who didn’t want to say.
The raw data from the form is stored in a
Google Docs spreadsheet. We then add the
key information from the spreadsheet as a
layer in Google Maps Engine Pro. Importing
the data creates a pin on the postcode for each
technical communicator, and, if you click on a
pin, you’ll see the person’s gender, job status
and years of experience. For privacy reasons,
the map doesn’t contain any information on
the person’s name or email address.
At the moment, the map doesn’t update
automatically each time a new record is added.
There’s a little manual intervention needed to
import the latest data points onto the map.
The map and its findings
We now have enough data (over 270 entries) to
have a representative sample, and have started
analysing the data.
At the time of writing (August 2014), the
map looks like Figure 1.
The red pins identify the location of
employees, the blue pins freelancers, and the
white pins people who didn’t want to say.
Figure 2 shows a larger map of the most
populated areas.
We can see that technical communicators
are clustered around a number of locations.
Figure 2. Red shows location of employees, blue pins show
freelancers, and the white pins people who didn’t want to say.
1 Introducing Tech Comm on a Map
http://ffeathers.wordpress.com/2014/05/07/introducing-tech-common-a-map
2 http://sarahmaddox.github.io/techcomm-map
17
Popular locations include Bristol, Cambridge,
Gloucester, Greater London, Manchester,
Newcastle, Nottingham, Sheffield and
Southampton. This matches with the primary
locations for organisations in the software and
aerospace sectors.
What’s of equal interest is the locations
where there are gaps. The areas that stand
out are: Glasgow, Leeds and East Yorkshire,
the West Midlands and the western half of
the Thames Valley. These are places where
prospective employers might not expect there
to be a shortage of suitable local candidates.
Figure 5. ISTC number of members, distributed
by location. Data: 2012. Originally published in
Communicator Winter 2012.
Figure 3. There are slightly slightly more men
(marked with blue stars) than women.
(Figure 4) it confirms the locations where there
are shortages of technical communicators, with
the exception of two areas: Birmingham and
Glasgow.
It also suggests new clusters: one around
Colchester and Ipswich, and another around
Cardiff. The map still needs data, so if you are a
technical communicator, please add your details
to the map. You never know, you might find
there’s a technical communicator living in the
street next to yours.
Editor’s note: The ISTC created a similar map
based on ISTC membership in 2012. An article was
published in Communicator Winter 2012. Figure 5
shows the distribution of ISTC members. C
References
Cherryleaf (2014) ‘Cherryleaf Survey – Location of Technical Authors map’
www.cherryleaf.com/useful-resources/cherryleaf-survey-2014/
(accessed July 2014)
Maddox S (2014) Introducing Tech Comm on a Map
http://ffeathers.wordpress.com/2014/05/07/introducing-tech-comm-ona-map (accessed July 2014)
Maddox S (2014) ‘Tech Comm on a map’
http://sarahmaddox.github.io/techcomm-map (accessed July 2014)
Truscott R (2012) ‘Area groups get going’ Communicator Winter 2012: 12–13
Figure 4. Technical communicators including
ISTC members.
Figure 3 shows the genders.
There are slightly slightly more men (marked
with blue stars) than women.
When the ISTC membership data is added
Ellis Pratt is a director at Cherryleaf, a
technical writing services company.
W: www.cherryleaf.com
Tw: @ellispratt
18
Digital publishing
The e-book explosion
Independent publisher Toni Ressaire explains why the
publishing industry needs technical communicators.
To enter emerging
roles in publishing,
technical
communicators
are equipped with
a coveted set of
transferable, core
skills.
Figure 1. The
rapid evolution
of publishing and
the explosion of
e-books sales offers
new opportunities
for technical
communicators.
Toni Ressaire
turned her technical
communication
skills toward
publishing. “Ashes,
Ashes” by Tamara
Shoemaker is one
of several books
released by Toni’s
company, Route 11
Publications.
Once the world of publishing existed in a
small, but concentrated bubble located in large,
exclusive, and unapproachable publishing
houses. Aspiring authors pitched their stories to
the publishing houses with fear, trepidation, and
the illusive dream of producing a bestseller. They
considered themselves among the elite if they
received any response at all, even in the form of
the dreaded rejection letter.
Fast forward to 2014. Authors are turning
to self-publishing and independent publishers
to realize their dreams. They release e-books
before the printed version hits the market, if
they choose to release in print at all. They hire
editors and book designers. They send their
manuscripts to technology engineers who
convert their content to various digital formats.
Publishing houses, many of them already behind
in this evolving industry, are scrambling to
create digital departments or outsource backlists
of printed books for digital conversion. In the
digital evolution, chaos reigns.
What does publishing have to do with technical
communicators? Technological advances in
all fields are blurring the lines of traditional
roles. Technical communicators now have
opportunities to expand their services. To take
on emerging roles in publishing, technical
communicators are readily equipped with a
coveted set of transferable, core skills.
This article will include a brief history and
explanation of the rapid changes in publishing
and the new demands. The article will focus
on core skills that technical communicators
can exploit to meet these demands and explain
how they can position themselves as service
providers.
Evolution of publishing
In 1930, Chicago native Robert Carlton Brown
wrote The Readies, an eerily prophetic manifesto
published by Rice University Press.
“The written word hasn’t kept up with
the age,” Brown wrote. “The movies have
outmaneuvered it. We have the talkies, but as yet
no Readies.”
Brown, a rather avant-garde thinker, proposed
a revolutionary type of book:
“Writing must become more optical, more
eye-teasing, more eye-tasty, to give the word its
due and tune-in on the age. Books are antiquated
word containers. Quick-brown-fox-leaping-overlazy-doggy, uptodate, modern word-conveyors
are needed now…I must have a machine…a
simple reading machine which I can carry or
move around, attach to any old electric light plug
and read hundred-thousand-word novels in 10
minutes if I want to, and I want to.”
While reading “hundred-thousand-word novels
in 10 minutes” may have not yet been realized,
Brown’s further description of his reading
machine sounds familiar to today’s users of
digital reading devices.
“My machine is equipped with controls so the
reading record can be turned back or shot ahead,
a chapter reread or the happy ending anticipated.
The magnifying glass is so set that it can be
moved nearer to or farther from the type, so the
reader may browse in 6 point, 8, 10, 12, 16 or
any size that suits him.”
Brown even dreamed of books being sent over
airways; perhaps a foreshadowing of content
delivered digitally over wireless networks?
Brown went on to experiment with creating
a reading machine. His idea did not take off,
but his nearly forgotten manifesto shows that
digital publishing is not as new an idea as we
may believe.
Fifty years later, in July 1971, Michael Hart
digitised public domain works on a computer
and launched Project Gutenberg. The invention
of the Internet boosted the project, allowing the
transmission of digital data.
In 1996, Pierre Schwitzer, living in Strasbourg,
France, developed the @folio project, a mobile
reading device that could download any format
of text or illustration from the Web or from a
hard disk. Unfortunately, Schwitzer never found
funding to launch the prototype.
In 1998, Barnes & Noble funded the launch
of an e-book reader, the Rocket e-book, which
connected to the Web via a cable. The Cybook
was launched in January 2001 as the first e-book
reader in Europe. Neither of them lasted, due
to the high cost of the devices and the lack of
e-book selections.
Online bookstores grew. Academics and
commercial publishers continued to digitise
content. E-book formats and reading devices
came and went. But in the traditional publishing
industry, e-books were still an afterthought to
printed books.
In 2007, something extraordinary happened.
Amazon launched the Kindle reader and it sold
out in five-and-a-half hours. An increase in
e-book sales followed.
A 2010 study by International Data
Corporation (IDC) reported that worldwide sales
for e-readers was at 12.8 million units shipped
that year, up from $3 million in 2009. One year
later, in 2011, IDC reported that e-reader sales
had doubled, coming in at 23.2 million units
19
sold. In that same year, Amazon reported that it
had sold more e-books than printed books. The
e-book had finally reached maturity and was
gaining respect.
Behind the scenes, the publishing industry was
evolving in other ways. Desktop publishing, the
Internet, and the evolution of digital devices and
formats were opening publishing to new markets.
No longer were deep pockets and brick-andmortar bookstores required to publish and sell
books. Smaller independent publishers sprang
up. Enterprising authors learned how to publish
their own books, and service providers began to
fill the gap for less-than-enterprising authors who
wanted to by-pass the traditional houses.
And what was happening in existing publishing
houses? Those who were not early adopters were
scrambling to convert their printed backlists to
digital. They were producing more e-books to
meet the digital demand and revamping their
production departments to make use of the new
technologies.
Document anagement
The lack of a standard format creates
opportunities for technical communicators with
single-sourcing and document management
experience. Each e-reader and digital distributor
requires a different format and file type. Kindle,
for example, requires a proprietary MOBI file
format, while most other e-readers use the EPUB
format. So, for one book published, at the very
least one must produce a printed format, a
Kindle MOBI and an EPUB. Add to this congestion
the fact that all EPUBS are not created equal.
Apple requires all EPUBS to pass a rigid set of
requirements; an EPUB that makes it through
Kobo’s obstacle course may get kicked back
by Apple.
Document conversion
The evolution of the publishing industry has
changed the roles, job descriptions and even
required skill sets in the production of the
printed and digital word.
The evolution is not yet mature. The
technological parameters of digital publishing
continue to evolve. This evolution presents
numerous opportunities for technical
communicators.
While traditional roles for researchers, editors,
translators, and print production layout and
design specialists continue to exist, a new set of
technical competencies is needed.
The following explores some core skills
by examining some of the tasks involved in
publication of an e-book.
Related to document management, conversion
could be considered a separate area of expertise.
As noted earlier, the lack of standard file
formats creates a need for a comprehensive
understanding of e-book formatting.
In addition to the various formats required by
e-readers, the distributors and aggregators that
send e-books to the various readers also require
various types of formats as the raw product. For
example, Amazon accepts PDF or Microsoft Word
documents. Amazon will do the conversion to
MOBI for you. On the other hand, Smashwords,
an aggregator that distributes to many different
types of e-readers, wants only Word files,
and the files must be formatted according to
Smashwords specifications.
Creating EPUBS, because of their complexity
for the technically challenged, has become
its own specialty area. EPUBS are basically a
collection of HTML files (see Figure 2). Technical
communicators with HTML knowledge would
hold an advantage in this area of publishing.
Project management
Editing
Publishing a book requires careful management
of multiple teams and multiple outputs. In
addition to the traditional printed product,
the book must undergo conversion to various
digital formats. There is no industry standard
e-book format.
While editing may seem an obvious skill set
needed in the publishing industry - and it’s
certainly not a new one - the opportunities for
editors have expanded.
As self-publishing and the emergence of
independent publishers have proliferated,
Transferable skills
For one book
published, at the
very least one must
produce a printed
format, a Kindle
MOBI and an EPUB.
Figure 2. EPUBs are basically a collection of HTML files.
20
Digital publishing
Content creation
Figure 3. Creating a book cover, front, back and spine, involves following
specifications for layout and trim sizes, and writing content for the back cover.
E-book covers have digital image specifications, depending on the distributor.
You may be surprised at some of the
opportunities that exist for writing content in the
publishing industry.
Along the more traditional lines of technical
writing, opportunities exist to write technical
content for software companies, hardware
companies, academic institutions and any
number of organisations looking to produce
technical content in the form of an e-book.
With the proliferation of applications and
software dedicated to this evolving industry,
numerous opportunities exist to create the everpresent user documentation.
But how about writing book front matter, back
matter, book descriptions, copy for back covers
or creating indexes?
And what about social media? Marketing
through social media is an integral part of
publishing. Crafting social media messages
requires writing effective content and brevity
(see Figure 4). These are hallmark skills of the
technical writer.
Emerging roles
Figure 4. Use a social media scheduler to carefully write - and rewrite - all social
media messages in advance, coordinating messages throughout the day and
week.
many authors and small publishers are in need
of editing services. Even the larger publishing
houses are sometimes contracting out for
editorial services.
Content/cover design
Again, the move toward self-publishing
and contracted services means technical
communicators with design experience are
finding new uses for their skills. Design in
publishing could range from printed to digital
documents for a wide range of formats, as
mentioned previously.
Printed books may follow any number of
specifications depending on page count, trim size,
spine width, paper quality and other variants.
Knowing how to follow the specifications outlined
by each print shop can be daunting for the
less-than-experienced, which includes most selfpublished authors.
Cover design is also becoming a specialised
service with expanded needs. Even if you’re not an
illustrator, taking existing artwork and following
specifications for digital and print publication
covers may offer new opportunities for showing
off your document design skills (see Figure 3).
Traditional, larger publishing houses also need
these services.
You’ve probably already been imagining some
of the roles a technical writer could fill in the
publishing industry. As you’ve been reading this
article, you may having been thinking, “Hey, I
could do that.”
While publishing houses need in-house
technical personnel with these skills, many are
out-sourcing some of these tasks. Numerous
independent and smaller publishing houses
are using contractors or service providers for
everything from editing to conversion.
Another rapidly growing need for publishing
services is emerging in the self-publishing
industry. A growing number of authors are
deciding to publish their own work themselves.
Amazon’s Kindle Direct Publishing branch
provides do-it-yourself motivated authors the
possibility to publish directly to amazon.com.
Other digital booksellers, such as Kobo, Apple
iBooks, Scribd and Smashwords also provide the
means for authors to publish their own works.
While many authors are taking advantage of
these rapidly expanding opportunities, they
often lack the technical expertise to navigate the
systems required to so do. They are turning to
services providers to help them reach their goals
of self-publishing.
Editorial services
Even the best writers need a second eye, and
sometimes a good storyteller needs some
assistance with copyediting. Getting all of those
commas in the right place is a challenge for even
bestselling authors.
Translation services
The self-publishing phenomenon has made
worldwide sales of e-books easy. Many of
21
the previously mentioned booksellers and
aggregators make it possible for a self-publisher
to make their books available worldwide in
online bookstores with the simple click of a
button. A language expert could find a role in
book translation.
Formatting services
Professional presentation can make or break a
book, especially from an unknown author. From
print-ready PDFs to properly formatted Word
documents, opportunities abound for technical
communicators to get manuscripts ready for the
press and digital market. Formatting is also timeconsuming, requiring multiple versions of the
same manuscript.
Conversion services
We have already seen how properly formatted
files for numerous types of digital formats can
overwhelm an author or even an over-worked
independent publisher. With a knowledge of
HTML and CSS and an understanding of the
various e-book formats in use, a technical
communicator could provide a valuable service
in publishing (see Figure 5).
Document management
As a technical communicator who has specialised
in single-sourced documentation, I’m developing
my own methods of single-sourcing manuscripts.
Tools like InDesign and Madcap Flare are
necessary to create multiple outputs from one
source document, a particular challenge in
today’s publishing industry.
Any service provider who can use conditional
formatting to create multiple outputs from one
source document just might get a big hug from
a frustrated author or publisher. Based on the
many conversations I have had with publishers,
service providers and authors and based on the
online literature, very few service providers exist
who can offer this expertise. If proven methods
have been developed, no one appears to be
publishing them.
Distribution management
While there are quite a few aggregators in
the industry, there are some advantages to
publishing directly to some of the larger online
bookstores; but managing many books and
many accounts with these online bookstores
is quite a task. Distribution management is
an emerging role in the industry. Account
management for each book published includes
pricing, tagging, selecting book categories,
managing ISBNs, writing descriptions and
author bios, and keeping all of this information
up to date as it changes. There are also some
marketing advantages for carefully managing the
distribution accounts, such as changing search
patterns among readers.
Figure 5: E-book conversion prices from
www.ebookpartnership.com
Evolution creates opportunity
The sales of e-readers and e-books have been
growing rapidly in the last decade; but this is still
an industry in flux. There’s no doubt that the
technological changes we are seeing provide
great opportunities for technical communicators
to use their core skills in supporting this
evolving industry. C
References
With HTML and CSS
knowledge and an
understanding of
e-book formats,
a technical
communicator could
provide a valuable
service in publishing
Brown, Bob (1930) ‘The Readies’ Rice University
Digital; (online) available at
http://cnx.org/content/m31518/latest/ (accessed
July 2014)
Lebert, Marie (2011) ‘eBooks:1998 - The first ebook
readers’, July 16, 2011; (online) available at
www.gutenbergnews.org/20110716/ebooks1998-the-first-ebook-readers/ (accessed July 2014)
Lebert, Marie (2009) ‘A Short History of EBooks’
NEF, University of Toronto; (online) available at
http://archive.org/stream/
ashorthistoryofe29801gut/29801-pdf_djvu.txt
(accessed July 2014)
Cain-Miller, Claire and Bosman, Julie (2011)
‘E-Books Outsell Print Books at Amazon’ The New
York Times, May 19, 2011; (online) available at
www.nytimes.com/2011/05/20technology/20am
azon.html (accessed January 2014)
IDC Corporate USA Press Release, March 10, 2011
(online) available at
www.idc.com/about/viewpressrelease.jsp?
containerId=prUS22737611
(accessed January 2014)
Toni Ressaire is a technical writer/
consultant and the publisher at Route
11 Publications, an independent
publishing company.
W: www.route11publications.us
22
Review process
Roughing it out with reviewers
If you’re writing documentation, then you need to ensure it’s
accurate. Geetha Haridas describes how to get it reviewed.
Introduction
Writers typically
work with technical
reviewers to identify
errors in documents.
Involve reviewers
early in the process
to ensure that
discrepancies are
identified at an early
stage.
End-user orientation, clear writing, and
attractive presentation of content are some
of the key attributes of good documents.
However, documents are truly worthwhile
only when they provide accurate information.
Incorrect information serves no purpose and
could be detrimental in use.
Writers typically work with technical
reviewers to identify errors in documents.
The attitude of reviewers towards the
documentation function has a deep
impact on the quality of reviews and the
resulting documentation. Unfortunately,
negative perceptions such as ‘who reads
documents anyway’ and ‘writers simply make
documentation look pretty’ do exist. Therefore,
writers often find it hard to make reviews
more effective and gain acceptance as an equal
contributor towards product development.
Effective reviews require a two-fold effort:
setting the right expectations with reviewers
and communicating appropriately. This article
explores a few issues surrounding technical
reviews and offers some hints and tips for
defining a review process and working with
different types of reviewers.
Defining the review process
Formally defining a review process can help
you to set the correct expectation with your
reviewers and obtain information and feedback
throughout the documentation life cycle.
To define a review process, clarify your
documentation requirements and milestones,
identify your reviewers and involve them early
in your documentation lifecycle.
1.Create a documentation plan and schedule
Reviewers often ignore documentation
reviews when they are under pressure to
meet their own deadlines. A documentation
schedule can help you to coordinate with
reviewers to allocate sufficient time for
reviews.
Even if you work in an environment where
consistent processes and procedures do not
exist, ensure that you create a documentation
plan to:
Identify the key stages of your
documentation lifecycle and the review
milestones.
Clarify the tasks and effort involved in
producing documentation.
When you have a formal documentation
plan in place, reviewers are more likely to
appreciate the effort involved in producing
documentation and take technical reviews
seriously.
2. Identify your reviewers
Identify reviewers who understand the
importance of your documentation. In
addition to working with engineers, involve
product managers, development managers,
and support managers, who may have a
broader view of project-related issues. These
personnel can also point you to other useful
sources of information and notify you about
any changes in the scope of the project.
3. Involve reviewers early in the process
This helps to ensure that discrepancies are
identified as soon as possible, for example,
when you are creating the outline for your
document. Reviewers involved early in the
process are also likely to feel accountable for
the documentation that you produce.
Working with different types of reviewers
In an ideal world, writers expect reviewers to
understand the challenges in producing quality
documentation and provide valuable input
throughout the documentation cycle. Writers
also expect reviewers to proactively share their
knowledge and answer queries on demand.
However, to the writers’ disappointment,
reviewers often fall into one or more of the
following categories.
Hello…Is someone out there?
Reviewers of this type feel that any
involvement in the documentation process
is a waste of their time. They rarely respond
to writers’ queries. Writers usually find it a
challenge to establish two-way communication
with these reviewers.
Hints and tips:
If you primarily communicate by sending
emails, then change your communication
technique when working with these
reviewers. Apart from sending emails, meet
these reviewers personally or speak to
them over the phone.
Never send emails with trivial questions,
as your reviewers are likely to become
deterred from responding to your queries.
Instead, consolidate your queries and send
them in a single mail.
Everything is fine (always?)
While some reviewers do respond to writers,
they always suggest that the content is of
excellent quality. However, this might be a
23
risky situation where reviewers might be
ignoring the documentation and providing
positive feedback just to keep writers happy.
Hints and tips:
In general, these reviewers do want to
respond to you, but probably find it
overwhelming to go through the details of
the documentation.
Draw the attention of these reviewers
to specific issues. Send them a list of
questions along with the documentation.
To help them to quickly review the
essential content, highlight your queries
within the document. Continue to ask
pertinent questions.
Nothing is fine (always again?) and do as I say
This is the nitpicking category of reviewers
who believe that writers can never get it right.
Reviewers from this category might even
pick on editorial issues and question wellestablished rules of technical writing. While
these reviewers do offer feedback during
technical reviews, they tend to be possessive
about the words they contribute and try to
control the final output.
Hints and tips:
Reviewers of this type can be difficult to
please, and very rarely can you work with
them without involving your (or their)
manager.
When they point out perceived issues in
the documentation, ask them to give you
precise explanations and justification for
their comments. Educate them about your
writing guidelines: offer them a copy of the
technical writing department’s style guide.
To avoid the potential problem of rewriting
large chunks of documentation to satisfy
your reviewers just before a product
release, report any issues to your (or their)
manager early during the process.
Too many cooks?
When multiple reviewers review a document,
writers might find it difficult to coordinate
with them, either because the reviewers
offer contradicting feedback, or refuse to
take ownership, which then results in the
documentation being ignored.
Hints and tips:
Minimise the number of reviewers who are
required to review your documentation.
If you must involve many reviewers,
designate one of the reviewers as the
primary point of contact who can
consolidate review feedback (say,
per functional area) and help resolve
contradicting review comments.
Some general dos and don’ts
Writers must often use different strategies
to work with different types of reviewers.
Yet, the attitude of reviewers towards the
documentation is also shaped by how writers
perceive their own work and carry out their
own responsibilities.
To ensure that you get the support you need:
Ask for help when required, but do your
homework before you start writing, before
you ask questions, and before you send
documents for review.
Be confident when you ask for product
demonstrations and source information.
Remember that you are an equal member of
the product development team.
Escalate issues early in the process. If your
reviewers are difficult to work with, get help
from your (or their) manager.
Respect your reviewers’ time. Remember that
your reviewers have their own deadlines to
meet: demonstrate your empathy.
Integrate with the rest of the product
development team. Gain the acceptance
of your reviewers by making your
documentation useful for them, for
example, by sharing your documents with
new Engineers who want to gain product
knowledge. Maybe offer them formatting
or editorial help with one of their own
documents.
Apply your skills to resolve larger issues, for
example, give your suggestions to enhance
the usability of user interfaces.
Do not be over-accommodating or accept
unnecessary criticism from reviewers.
Avoid over-communication.
Remember
that you are an
equal member
of the product
development team.
Conclusion
Reviewers form an indispensable part of the
documentation process, and writers cannot
function without them. Writers can help
reviewers to understand the importance and
impact of documentation reviews. Tools,
knowledge, writing skills do enhance the
profile of a writer, but writers can produce
accurate information only if they know how to
work with a range of reviewers. Writers must
know their reviewers, demonstrate their
capabilities, and build constructive
professional relationships. Communicating and
responding appropriately is the key to
resolving most of these issues. C
Respect your
reviewers’ time.
Geetha Haridas is has over 14 years
of experience in designing and
developing software product
documentation. She currently works
as a technical author at Ubisense,
Cambridge.
24
Global content strategy
The ever-changing face of content
New technology brings new challenges: Louise Law discusses
how global content strategies are changing to keep up-to-date.
When John Chambers, CEO of Cisco, referred to
the “Internet of everything” at the 2014 World
Economic Forum in Switzerland, I think he
meant to say the Internet of all things content. I
live and breathe content, not only in my role at
Welocalize but also in the industry I work in.
We’re all in the business of content creation
and translation, technical and otherwise. We
know that content creation, development and
delivery have changed significantly over the
years due to the Internet and the explosion in
technological advances. The resulting changes
are massive growth of the online consumers
with a healthy appetite for loads of new content
in their own languages.
There are more advanced content-creation
tools, improved applications for posting
content and growing revenue opportunities
to be made from posting global content. All
this has fuelled the growth in more and more
content being published to reach our intended
content consumers, which is great news for
content authors and creators.
It’s not just the volume of content and
information that is growing rapidly; it’s also
the type of content that is being published.
Traditional printed manuals are reducing
in number as global organisations are now
publishing digital content that can be searched
for and updated quickly. This tends to be much
more cost-effective in this “on-demand” world
we live in.
Physical printed matter is no longer the
primary or most profitable means of delivering
content and engaging with consumers.
Consumers today want to be more involved in
providing feedback, reviewing products and
then share it with everyone! A good example
of this is the exponential growth in social
media models and user-generated content
(UGC). As people access content through
their never-ending supply of readily charged
mobile devices, being able to engage and take
part in the conversation gives them a voice
to influence lifestyles, trends and the way
business is done.
UGC and crowdsourcing technical documentation
UGC has been featured in technical forums for
many years; however, the recent global growth
in UGC, in some cases as a business model,
has been explosive. UGC is produced through
an open collaboration approach, created by
participants and site visitors. Types of UGC can
range from blog comments, message board and
forum posts, input on review sites, comments
on articles, wikis, social media, microblogging
and social media posts on popular sites such
as Twitter and Facebook. Billions of dollars
have resulted from the UGC model in revenue,
advertising, apps and more. The most common
examples of huge enterprises using the UGC
model are YouTube, Instagram, Twitter,
Facebook, eBay and TripAdvisor, just to name
a few. Other business models that rely heavily
on UGC through article feedback and contentinfluencing are abundant on the web and
include Amazon, CNN and IMDB.
Does the growth in digital content affect all types of
content?
Yes. However, you might think that growth in
global content, changing publishing models
and shifting content types would not affect
technical communications: how does a massive
growth in social media, UGC and ecommerce
affect complex technical manuals and online
help systems?
Any shift in the way we engage and
communicate with our consumers will affect
content. The same applies for the changing
ways in which online information is consumed
and the expectations of your communities.
The huge, growing amounts of content
available on the Internet seems to have had an
inversely proportional effect on the attention
span of a consumer. If this article were online,
I probably would have lost a few of you by now
as people “bounce” quickly, meaning that they
don’t spend long on one item. A lot of people
(and I’m guilty myself), tweet articles without
having read the whole piece and will quite often
post comments on a piece of content without
finishing it. Our attention spans are limited, as
well as our time to consume the vast volumes
of words posted online every day.
We have to adapt our content for a
generation of Internet consumers who expect
relevant information upfront and are used
to instant gratification and quick fixes. They
expect data and information to be presented
in an entertaining and engaging way,via
sophisticated multimedia techniques, and more
use of images and video footage.
Consumers expect to be able to have a more
personal engagement with products. Rather
than sending out information along a one-way
street, global brands have to enable a more
two-way interaction so that consumers can
have a more personal, intimate experience,
provide feedback and have conversations with
like-minded people. Even the most detailed,
25
complex content will evolve to reflect that
personalisation.
Some global organisations are seeing new
approaches to developing and publishing their
technical communications. I am seeing more
and more organisations socialising product
documentation into web-based communities
using some UGC techniques. Consumers can
interact with technical content, comment and
make suggestions for improvements. With the
growth in crowdsourcing, people with close
relationships with the product can become
more involved in the creation of content
using an intelligent crowdsourcing or
community model.
Examples of open innovation community
forums include Betavine (Vodafone), Connect
+ Develop (P&G), BMW Customer Innovation
Lab and My Starbucks Idea. This interactive
approach is more popular for certain industry
sectors – especially the consumer sector. It is
wise for organisations looking to create loyalty
and high levels of engagement, no matter what
the industry, to interact with the dedicated
group of users and fans who all have a personal
involvement and investment with specific
products and services.
Content means revenue
Whether marketing, product or technical
content, big digital organisations are taking
content and content strategy very seriously
as a direct source of revenue. Companies like
eBay, Facebook and Twitter, for example, all
simply publish or facilitate the publishing of
content and as a result, make masses of money
by wrapping advertising around it. In July 2004,
the valuation of Facebook was $192 billion
after a good first quarter earnings. Facebook
is only 10 years old and yet it now reaches 1.3
billion consumers around the world1. Since its
launch in 2003, LinkedIn now has 225 million
members and has its sights set on becoming a
professional publishing platform, creating and
distributing business content.
The numbers speak for themselves of what
these giant publishing platforms mean to the
global economy today.
Avoiding the silo
The traditional models for content creation
often happen in “silos”. Corporate marketing
develops its content and each product
business unit produces its own set of
communication materials, such as product
guides, technical manuals, help references
and FAQs. These materials may be authored
and published on different continents, using
a variety of authors, tools and processes.
Coordinating a global content and localisation
strategy, while still operating in silos, can be
very frustrating and result in very fragmented
content style and disjointed brand and
user experience. It can drive authors and
translators to distraction, creating, editing,
and storing content this way. This can make
localisation challenging. The worst-case
scenario is that it can cost your consumers
and hurt your revenues.
Digital content is now more widely available
to everyone, everywhere, 24/7. So, if content
has been created in separate silos, people will
notice. Each piece of content is accountable
for what could be billions of dollars of brand
equity. Running a content strategy in a
traditional silo model is old hat and can be
detrimental to business. You need to know
where all of your content is and manage the
source and translated versions to gain optimal
benefit, globally.
The global content strategy
It is fair to say that most organisations with
international growth targets need to have a
central content strategy that supports their
global intentions. Organisations generate
millions of words each year, whether
marketing and training collateral or complex,
detailed instructions on how to use a product.
Having a global content strategy in place not
only provides a structure for managing all of
your source content; it considers consumers
in all target markets and supports the need to
publish content in languages other than the
source.
Here are some simple questions that
need to be answered when defining a global
content strategy:
Who is my audience and how can I define
them demographically?
Where are they located?
Why will they be interested in my content
(using socio-graphic and psycho-graphic
assumptive data)?
When do I need to publish the content to
make sure I get the most views?
How will they consume my content and
how will the content be published and in
what format?
What are the best authoring tools to use
when creating the source content? (What
are the localisable components?)
For a global audience: What are the
localizable components of the content and
what is the supply chain needed to perform
translation and localisation?
Content must be readable, targeted,
accessible and searchable. A key component
of many types of digital content for all target
languages is search engine marketing (SEM),
which can be split into two primary areas:
SEO (organic search) and PPC (paid search).
SEO is important: it means that content gets
exposure to the right people, plus competes
for appearance on the all-important first page
search results.
1 http://expandedramblings.
com/index.php/by-thenumbers-a-few-importantlinkedin-stats/#.U-DH9fldVZt
26
Global content strategy
Impact of global content on localisation
and translation
While I was trendspotting at Localization
World 2014 in Dublin in June, one of the
most noteworthy trends was the increasing
significance of the role of the global content
strategy. It was surprising how many people I
met with the word “content” in their job title.
Content - marketing, technical or otherwise
– is best placed within the global content
team, including the responsibility of making
content available in all target languages. Many
content teams aren’t centralised, but I got the
impression that they certainly wanted to be.
A global content strategy can only be global
if it speaks many languages. Scott Abel, The
Content Wrangler, ran an excellent content
Some relevant statistics
The indexed web now contains at least 3.3
billion pages
(www.worldwidewebsize.com, 10th July 2014).
Worldwide ecommerce sales to increase nearly
20% in 2014 – B2C ecommerce sales worldwide
will rise nearly 20% to reach $1.471 trillion in
2014 (emarketer, 2014).
78% of B2B Marketers are creating more
content than they did a year ago (RCMI 2014
Benchmark Report).
strategies track at Localization World. From
a languages perspective, localisation has
to move further upstream into content
marketing strategies so that translation is
a planned and natural part of the content
management cycle. Localisation and
translation must be part of the planning stage
and consider localisation at the source.
Conclusion
For the entire content supply chain to work
together we must continue to work together,
as a content community, within the corporate
walls and outside. If we break down the silos
and find ways to collaborate, everyone
benefits. We are all on the Internet and it now
drives so much of what we do. Working
together will make sure we provide the best
user experience, for all content, with the
highest standards of quality to our mostvalued audiences. C
Louise Law is global writer and
marketing communications manager
at Welocalize. She has worked in
communications for over 20 years and
holds a degree in marketing.
W: www.welocalize.com
www.facebook.com/welocalize
ƌĞǇŽƵŝŶƚĞƌĞƐƚĞĚŽƌŝŶǀŽůǀĞĚŝŶ
ƚĞĐŚŶŝĐĂůĐŽŵŵƵŶŝĐĂƟŽŶ͍
tŽƵůĚǇŽƵůŝŬĞƚŽ͗
ͻ<ĞĞƉƵƉƚŽĚĂƚĞǁŝƚŚƚƌĞŶĚƐĂŶĚƚĞĐŚŶŽůŽŐŝĞƐ͍
ͻ^ĂǀĞŵŽŶĞǇƚŚƌŽƵŐŚĂĐĐĞƐƐƚŽĚŝƐĐŽƵŶƚĞĚĞǀĞŶƚƐ͕ƚƌĂŝŶŝŶŐĂŶĚƌĞƐŽƵƌĐĞƐ͍
ͻ<ĞĞƉŝŶƚŽƵĐŚǁŝƚŚƚŚĞh<ƚĞĐŚŶŝĐĂůĐŽŵŵƵŶŝĐĂƟŽŶƐŝŶĚƵƐƚƌǇ͍
ͻ>ŽŽŬĨŽƌǇŽƵƌŶĞǆƚũŽďŽƌƌĞĐƌƵŝƚƐŽŵĞŽŶĞƚŽĮůůĂǀĂĐĂŶĐǇ͍
ͻ'ĂŝŶĂĚǀŝĐĞŽŶƉƌŽũĞĐƚƐĨƌŽŵƉĞĞƌƐ͍
ͻ&ĞĞůůĞƐƐŝƐŽůĂƚĞĚŝŶǇŽƵƌĞǀĞƌǇĚĂǇǁŽƌŬ͍
ͻ^ŚĂƌĞƐŬŝůůƐĂŶĚĞǆƉĞƌŝĞŶĐĞǁŝƚŚƉĞŽƉůĞǁŚŽĂƌĞŶĞǁƚŽƚŚĞƉƌŽ ĨĞƐƐŝŽŶ͍
ͻĐŚŝĞǀĞƌĞĐŽŐŶŝƟŽŶĂŵŽŶŐƐƚǇŽƵƌĐŽůůĞĂŐƵĞƐĂŶĚƉĞĞƌƐ͍
ͻ^ƵƉƉŽƌƚƚŚĞ/^dŝŶƉƌŽŵŽƟŶŐƚŚĞƉƌŽĨĞƐƐŝŽŶŝŶďƵƐŝŶĞƐƐĂŶĚĞĚƵĐĂƟŽŶ͍
/ĨǇŽƵŚĂǀĞĂŶƐǁĞƌĞĚ͚ǇĞƐ͛ƚŽŽŶĞŽƌŵŽƌĞŽĨƚŚĞĂďŽǀĞ͕
ƚŚĞŶǁŚǇŶŽƚũŽŝŶƵƐƚŽĚĂǇ͊
ŽŵŵƵŶŝĐĂƚŽƌ:ŽƵƌŶĂů
dĞĐŚŶŝĐĂůŽŵŵƵŶŝĐĂƟŽŶh<
/^dŽŵŵƵŶŝƚǇ
WƌŽĨĞƐƐŝŽŶĂůĞǀĞůŽƉŵĞŶƚ
ĂŶĚZĞĐŽŐŶŝƟŽŶ
dĞĐŚŶŝĐĂůŽŵŵƵŶŝĐĂƟŽŶ
ZĞƐŽƵƌĐĞƐ
/^dŵĞŵďĞƌƐĂƌĞƐĞůĨͲĞŵƉůŽǇĞĚ͕ƐŽůĞƐƉĞĐŝĂůŝƐƚƐŝŶƐŵĂůůĐŽŵƉĂŶŝĞƐ͕ŽƌƉĂƌƚ
ŽĨůĂƌŐĞƌƚĞĂŵƐĂƚŽƌŐĂŶŝƐĂƟŽŶƐƐƵĐŚĂƐ͗ĐĐĞŶƚƵƌĞ͕ZD͕t͕^ǇƐƚĞŵƐ͕
,ĞǁůĞƩͲWĂĐŬĂƌĚ͕,^͕/D͕E,^͕YŝŶĞƟY͕ZŽůůƐͲZŽǇĐĞ͕^ĂŐĞ͕dŚĂůĞƐ͕
tĂŝƚƌŽƐĞ͕tŽƌůĚWĂǇ͙ĂƐǁĞůůĂƐĂŚŽƐƚŽĨůĞƐƐǁĞůůͲŬŶŽǁŶĐŽŵƉĂŶŝĞƐ͊
dŚĞ/ŶƐƟƚƵƚĞŽĨ^ĐŝĞŶƟĮĐĂŶĚdĞĐŚŶŝĐĂůŽŵŵƵŶŝĐĂƚŽƌƐŝƐƚŚĞůĂƌŐĞƐƚ
h<ďŽĚǇƌĞƉƌĞƐĞŶƟŶŐŝŶĨŽƌŵĂƟŽŶĚĞǀĞůŽƉŵĞŶƚƉƌŽĨĞƐƐŝŽŶĂůƐ͘
^ĐĂŶƚŚĞĐŽĚĞǀŝĂĂĚŽǁŶůŽĂĚĞĚYZƌĞĂĚĞƌĂƉƉŽŶǇŽƵƌƉŚŽŶĞ
ϰ͘ϭϮ
XML authoring
A hybrid approach to XML conversion
Maxwell Hoffmann from Adobe continues discussing his thoughts
about XML and shares how to convert documentation to XML.
Is it ‘all or nothing’ when it comes to XML Authoring?
For years we’ve all been hearing that we will
surely perish if we don’t completely migrate
our content to XML structure within the next
18 months. Obviously these predications are
somewhat exaggerated based on our collective
observation of a large chunk of technical
communication professionals who continue to
author without XML.
The reality is that in the near future, most of
us will need to author and maintain some (if not
most) of our content assets in XML to enable
creation and use of intelligent content. The
reality, though, is that there will continue to be
some short-lived publications that have no real
need to be shared or re-purposed. Occasionally,
we may need to create a ‘one-off’ document or
project that does not match most of our content
either in structure or formatting.
The ‘all or nothing’ approach that is
proposed by many solution members can
be intimidating. Do we really have to create
a new DTD and format style sheets for
meeting minutes, a conference abstract or our
department’s holiday newsletter? (I have actually
heard some experts answer this questions with
‘yes’ at major conferences.)
There is another path to take
Fortunately, most of us are not in a situation
where 100% of the content we author through
the rest of this century must be in XML chunks.
Moving forward, however, we do need to make
plans for eventual migration of critical business
intelligence into XML for a variety of reasons
that are outlined later in this article.
As I covered in my last article, “Overcoming
the ‘Fear Factor’ during migration to XML/DITA,”
XML can seem intimidating at first glance. There
is a level of complexity to the inherent rules
and structure of XML that cannot be entirely
avoided. Fortunately, not every member of your
team needs to become a Jedi Knight when it
comes to mastering arcane rules of parental
containment and auto-insertion of siblings,
although a few members of your XML transition
team will need to be expert in these areas for
the purpose of analysis and planning. Authoring
solutions like FrameMaker make the actual
authoring process streamlined and relatively
simple.
A good analogy is that an automobile
driver needs a theoretical understanding of
transmission, but they don’t need to know how
to build or repair it. In a similar fashion, XML
authors only need a general understanding of
the structure rules that, govern where they can
place certain elements.
The main point of ‘hybrid publishing’ with
Adobe FrameMaker 12 is that you can author
well-formed, ‘unstructured’ documents to meet
your immediate publishing needs as you refine
your XML solution. As you author new content
‘from scratch’ in XML via FrameMaker, you will
find it a relatively straight-forward process to
convert your unstructured files to XML.
Recent developments that will assist you
Some authoring products have made progress in
helping to ‘hide the complexity’ of XML during
most of the authoring process. At a minimum,
element tags may either be shown, or hidden
to reduce clutter on the screen. However, only
one authoring solution will allow you to easily
create well-formed but ‘unstructured’ content,
and eventually use a semi-automatic process to
convert that content into well-formed XML. That
product is Adobe FrameMaker 12.
Why? FrameMaker started out with an
inherent form of format-based document
structure that in many ways closely parallels
basic XML structure. In addition, FrameMaker
has generally penalised users for departing
from template standards or applying random
format overrides.
Most XML Authoring tools (including
FrameMaker) have DITA 1.2 support, with
‘out-of-the-box’ formatting that is simple, yet
reasonably attractive. A modest amount of
corporate ‘branding’ in headers and footers
is not difficult to achieve with any solution.
So, you may be able to get up and running
without having to create an XML application
‘from scratch.’ Note: if you do require extensive
customisation, ‘fancy’ PDF and the ability to
instantly publish to popular on-line formats,
FrameMaker becomes an even more obvious
choice, due to the comparative simplicity for
custom formatting.
Before going further into a painless model
for XML conversion, there are some important
questions to ask.
Do you really need XML?
This is the first question to ask before
embarking on setting up an XML authoring
system. Or at the very least, you should ask
whether your organisation could get value from
using XML. There is no question that there is a
cost to setting up an XML system. Before making
the investment, you should be sure that it will
benefit your organisation, both within itself, and
27
28
XML authoring
When the answer
might be ‘No’, you
don’t need XML.
The following
conditions would be
some indicators that
XML is not critical:
If your organisation
is a security ‘silo’
which cannot share
information with
outside parties
If your content is
not updated more
than once per year
If you have a
modest number
of documents
or projects of
moderate length
You have limited
staff resources with
a high ‘turn over’
rate, and constant
training of new
team members is
not an affordable
option
Since nearly any
enterprise will
answer yes to
many of the list of
questions about
needing XML, it
can be assumed
that you need to
prepare for an
eventual conversion
to XML. The steps
and considerations
necessary are
surprisingly simple
and logical.
through the sharing of your assets with other
organisations.
Ask yourself the following questions:
Do you localise your content?
Is it important to share information assets
with other organisations?
Is your authored content an important
business asset?
Do you need to support different authoring/
management tools to operate on the same
content?
Do you need to mix and match content in
different publications?
Are you interested in ‘intelligent content’ or
‘adaptive content’?
Is collaborative authoring important?
Do you need to comply with existing
standards (S1000D, DocBook, DITA, etc.)?
This list could be longer. The more questions
you answer ‘yes’ to, the more likely it is that
you need XML for some or even all of your
content. Because XML allows you to assemble
‘documents’ with components or chunks, your
content reuse will increase dramatically, and
your word count for localisation will decrease
exponentially.
A simple overview of migration to XML via FrameMaker
In this article, we cover most, but not all steps
involved in the process. Due to the complexity
inherent in XML itself, it would take more
than 3 pages to cover the topic thoroughly.
We take considerable liberties in extensively
quoting sections from an excellent Adobe White
Paper authored by Chris Despopoulos, The
Hitchhiker’s Guide to XML.
If you need
supporting
evidence to
convince your
management to
support you in this
endeavour, read the
Adobe Tech Comm
blog, ‘Ten Reasons
to Structure Your
Content’ located at
http://adobe.
ly/18mkHdQ
Figure 1. Content analysis
Content analysis
Before building the structured application for
your proposals, you should analyse existing
projects such as proposals, to identify their
components and structure. Examine Figure 1.
You can create a ‘content map’ based on your
analysis. Your results from analysing these two
proposals would logically lead to the following
sequence of elements:
Title
Executive Summary
Executive Summary:Title
Executive Summary:Paragraph (one, only)
Project Description
Project Description:Title
Project Description:Paragraph (one or more)
Cost
Cost:Title
Cost:Paragraph (one or more)
Schedule
Schedule:Title
Schedule:Paragraph (one or more)
With FrameMaker, an EDD (Element Definition
Document) is used, this defines the structure
that FrameMaker will use when it loads
the structured document. It also maps the
structure to FrameMaker formatting. There
are several logical ways to start building your
EDD. A simple set of steps are outlined in The
Hitchhiker’s Guide to XML that visually cover this
process.
Once a complete EDD and other FrameMaker
structured application files are assembled for
this example, you would have a structured
document with nested structure that resembles
Figure 2.
29
Migrating unstructured files to structure/XML
If structure and XML can add value to your
planned information assets, then it follows that
migrating legacy assets to XML can add even
more overall value.
Structured FrameMaker includes a conversion
table utility that you can use to transfer
unstructured FrameMaker files over to whatever
structure is defined in your structured
application. Once converted to structure, you
can save the documents as XML to complete
the migration. Please note that this is a ‘one
time’ process. Moving forward you will use your
structured application to author projects and
files natively in XML format within FrameMaker.
Components in your document are mapped
to an element structure via conversion table
maps. Map-capable components include
paragraph tags, character tags, markers, crossreferences, and table components. You can
create a conversion table that works with a given
template, and automatically generate structured
copies of any documents that use that template.
TIP: What if your legacy documents don’t
match your desired structure? For example,
what if you want to use an XML standard that
is unlike your legacy documents? In that case,
you can create an interim EDD that matches
your document structure, and then convert
the documents to that XML. Once in XML, you
can use existing tools such as XSLT to further
modify your XML documents and bring them into
compliance with the standard you chose.
Steps you would take to migrate your legacy
documents via FrameMaker include:
Clean up the legacy documents
Create the conversion table
Generate your structured documents
Save the structured documents as XML
Cleaning up legacy documents
Unstructured FrameMaker authors are
not strangers to the idea of ‘structured’
documentation. FrameMaker includes report and
book templates that reward you for ordering
documents via headings, lists, and character
tags. Note that headings create a hierarchical
structure, which is not unlike the structure you
would declare in XML.
The first step for conversion is to make
sure your legacy FrameMaker documents use
designated templates as they were designed.
You should check the following:
Make sure variable definitions are up to date.
In addition, it’s best to use variable names
with no spaces in them.
Update all references in your documents,
including cross-references and text insets.
Correct any unresolved references.
For documents with conditional text, show all
conditions. Structured FrameMaker creates
XML that maintains your conditional text
settings. But when converting to structure,
you need to show all conditional text to make
sure it gets wrapped correctly in structure
elements.
Make sure the ordering of your content is
correct. For example, heading structure should
not skip heading levels. Heading1, Heading2,
Heading3 is correct, but Heading1, Heading3
is not.
Eliminate format overrides for paragraph,
character, and table formats. You can use the
Find/Change dialog box to search for these
overrides.
Creating the conversion table
Figure 2. A structure document example
The conversion process creates structured
elements from FrameMaker formatting
components such as paragraph tags, character
tags, markers, cross-references, and table
30
XML authoring
components. To begin the conversion, choose
a document that is representative of your
typical content. This document should contain
examples of all of the formatting tags that
would occur in your documents. These tags
should be used in their logical sequences
(as they would occur in documents), so a
formatting template that shows examples of
each paragraph tag in alphabetical order is not a
good example document.
To begin building the conversion table:
1. Open the example document you want to
use, and save a copy of it. This will be your
working document.
2. Open the EDD for the structured application
that you are converting to, and import
the element definitions into your working
document.
3. With the working document active, choose
StructureTools>Generate Conversion Table.
Select Generate New Conversion Table, and
then click Generate.
FrameMaker scans the working document and
creates a list of the formatting components
that occur in this document. Any tags that are
defined in a format catalogue but not used in
the document are not included in this list.
Further tests and iterative testing are required,
but eventually you will have a strong, working
default conversion table that should work with
most of your legacy documents. Again, the
more consistent your legacy files are, the more
‘automated’ your conversion process will be.
Conclusion
Unless you are setting up a publication
environment from scratch, it’s very likely
that you will have legacy unstructured
documents. If it’s worth the effort to create
an XML authoring environment, then it is
probably just as worthwhile to convert your
legacy to XML.
[The Hitchhiker’s Guide to XML Authoring]
In many organisations, the requirement is
to implement XML authoring for existing
unstructured publications. Consider running a
pilot project first, as a proof of concept. Begin
with analysis and create an EDD. Then manually
reproduce a representative document using that
EDD. This will verify that the EDD supports the
document constructs that you need.
Once the EDD is verified, begin building the
conversion table. This is an iterative process,
where you convert a portion of a document,
check the results, then move on to convert more.
Some of your legacy constructs may be
so complicated that it’s difficult to build a
working conversion. Build a conversion table
that handles most of your document, and
then you can use FrameMaker ExtendScript to
automatically find and fix any invalid structure.
Remember the 80/20 rule: It takes 20% of
the time to automate 80% of your work. But to
automate the last 20% of your work will take
80% of the time. If you have hit a wall with the
conversion table, maybe ExtendScript can take
over. If even that is too difficult to program,
then you can search for invalid structure in
your document and fix it manually. The amount
of manual fixes you need to make should be
very small.
Remember, converting a body of documents
to a structure is a one-time effort. C
Glossary
Intelligent Content: content which is not
limited to one purpose, technology or output. It’s
content that is structurally rich and semantically
aware, and is therefore discoverable, reusable,
reconfigurable and adaptable.
Adaptive Content: is content that is structured
so that a single item can be displayed across a
multitude of devices in many different formats
(e.g. print and mobile)
References and resources
Adobe microsite for XML Authoring:
www.authorxml.com (accessed August 2014)
Build a structured application (in FrameMaker)
http://adobe.ly/1sWbHEF
Despopoulos, C (2014) PDF White Paper: The
Hitchhiker’s Guide to XML Authoring
http://bit.ly/1sJw0VX (accessed August 2014)
FrameMaker Return-On-Investment XML
Calculator:
http://adobe.ly/PZ3RtS (accessed August 2014)
FrameMaker XML Author 12, product overview:
http://adobe.ly/1i8lvXG
Hoffmann, M (2014) Overcoming the ‘fear factor’
Communicator Summer 2014: 43–46
Introduction to XML (w3schools.com)
http://bit.ly/1sWbamo
Recorded Webinar, The Hitchhiker’s Guide to XML
Authoring, Part 1:
http://adobe.ly/1qR9Env (accessed August 2014)
Videos: FrameMaker XML Author 12 Features:
http://adobe.ly/1hPnzUl (accessed August 2014)
Maxwell Hoffmann is Adobe’s
Technical Communications Evangelist.
A former product manager for
FrameMaker at Frame Technology,
Hoffmann also spent nearly 15 years
working with multi-lingual production and XML
publishing for Language Service Providers (LSPs).
Maxwell works from a virtual office in Portland,
Oregon, USA, where his hobby is identifying and
collecting mid-Century antiques.
W: http://blogs.adobe.com/techcomm
Tw: @maxwellhoffmann
The Hitchhiker’s Guide to XML Authoring
Are you embarking on a journey towards XML authoring?
Download whitepaper
Learn more about XML authoring
Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.
© 2014 Adobe Systems Incorporated. All rights reserved.
32
Learning and communications
Laying the foundations for change
Creating a learning and communications architecture is like
building a house, say LEO’s Andrew Joly and Kayleigh Tanner.
How are learning
initiatives sustained?
Imagine you are building your own home
– your Grand Design dream come true.
You wouldn’t finish the decoration before
you invited the plumber to come in and
consider how the water system and boiler
could be added, would you? Nor would
you give your builders the plan for the
kitchen and expect them to construct an
entire working house from that alone.
Successful design and building relies on a
series of interconnected processes, which
must be meticulously planned and assessed
relative to one another to achieve the final,
effective, result.
Creating a good learning and
communications strategy is a lot like
building a house. Think about how you
communicate with your staff, whether it’s
a new policy, HR updates or health and
safety initiatives. Do you send emails? Do
you place messages on the intranet? Do you
put up posters around the workplace? The
fact is, while each of these methods alone
may have modest success, you are far more
likely to get the message across when you
think about the communications strategy as
a whole. This is what we call a learning and
communications architecture. Designing
and delivering a learning architecture
needs the same thought and planning as a
traditional architectural project.
Figure 1. ‘The building blocks of a learning architecture’
What is a learning and communications architecture?
Today’s workplace is very different to the
one we knew even five years ago, with more
effective engagement channels available than
ever. Whether we use email, texts, instant
messages, phone calls, adverts, billboards,
social media or anything else, we are all subject
to a bombardment of messages every day. It
is our job to make smart choices about where
our messages live and how they support each
other for the maximum impact in the most costeffective way. By harmonising your channels
for the whole learning and communications
strategy, you will get the best use out of them
and ensure they work together.
Why do we need to think about learning and
communications architectures?
Many years of experience have told us that in
most organisations, there are some employees
who are simply not engaging with even the
best designed e-learning courses. This may be
because they just don’t have the time, but most
likely it is because they don’t understand the
benefits of the course in the first place. This led
us to think about the way employees engage
with a learning experience. The drive to look
at how learners or an audience are aligned to a
programme has been with us ever since.
We also looked hard at how learning
initiatives are sustained. A good e-learning
33
course may be well received at the time - and
an initial analysis may show that the learners
have successfully taken the learning on board –
but how much do they remember the following
week? Or the next month? Or even a year
down the line? Unless tackled in the original
programme design, the learning drop-off may
be huge. We realised that much can be done
around the ‘core learning’ to keep content fresh
in the minds of learners.
The same principle applies for
communications. If a new process is being
introduced, it may not be enough to just use
email to communicate the change. Emails can be
missed, deleted or ignored so we need to think
about how to keep the message at the forefront
of people’s minds.
In order to create more deeply embedded and
sustainable learning and communications, we
need to design and create audience journeys,
rather than standalone engagements. In
learning, we should be starting with a strong
communications campaign to raise awareness,
looking at the best learning modes for delivery,
providing supplementary content around
the main message, and then delivering the
sustained engagements as refreshers, reminders
and prompts.
This is where we see the parallel between
the building blocks and how they stick
together in architectural terms. It’s the craft
of making everything work well together. Is
the chimney in the right place? Is the boiler
appropriate for the house size? Equally, is the
learning available on the right devices? Do your
employees know where to go to find associated
resources or materials?
Finding the right channels
Now we have established the need for a
comprehensive learning and communications
architecture, it’s time to find the right
channels for our messages. We start by
looking at available touchpoints and modes of
engagement, assessing whether or not they are
suitable and how they might work together.
While we want to maximise our engagement
to boost the impact, we also don’t want to
waste time or money on the wrong channels.
Just because social media is a useful way to
communicate quickly with a large group of
people, it doesn’t mean that your organisation
and staff are ready to learn by this delivery
method yet. We need to focus on the solutions
that will work.
Once we have evaluated all the available
channels, we then look at how they will
work with each other. How will your just-incase e-learning work alongside your mobile
performance support? How could physical
media (like posters or banners) reinforce the
messages and motivation communicated in your
email campaigns? How will your staff forums
add value to your intranet? Effective learning
and communication is now about creating the
right blend of materials for your business and
learners to maintain your important messages
or learning objectives over time.
How do we go about constructing a learning and
communications architecture?
We understand what needs to go into our
architecture, so now it’s time to start designing
it. It’s time to stop thinking one-dimensionally
and start joining together engagement, content
and tools for the best learner journeys and the
most effective results. To help you put your
architecture in place, you should be asking
yourself three questions:
1. What do you already have in place? There
is no need to reinvent the wheel. If what
you have is working, think about enhancing
it with additional channels. If you have an
engaged community of learners, use them.
If you have just bought a new suite of tablet
devices, work these into your architecture.
If you don’t offer work mobiles, consider a
Bring Your Own Device (BYOD) strategy.
2. What media do people respond to? While
everyone may have a PC or laptop, you may
find that they prefer to receive engagement
communications on their smartphones.
Even though the intranet exists and is used
for accessing information, your employees
may prefer to ask questions quickly and
informally over instant messages rather than
via the intranet forum. Align your learning
architecture to the way your staff use your
existing channels, rather than the way you
would want them to.
3. What is the appetite for innovation? Do
your employees embrace or resist change?
If they are up for something new, now could
be the time to revolutionise the way you
communicate. If they are apprehensive,
avoid going in all guns blazing. Instead,
think about making smaller incremental
changes over time.
Once we have established our answers to these
questions and before doing anything else,
we should relate them back to our business
strategy. Decide how you will approach your
learning design in the context of your shortand long-term business goals. Then look at the
needs of your audience. Look at the different
learning and communications modes you have
available and begin to plan how your audience
will respond and use them. Keep testing – what
works? What doesn’t? Iteration builds success
in design.
The building blocks of a learning and communications
architecture
When we started presenting the notion of
learning architectures to our clients, they often
came back asking for more precise guidance on
34
Learning and communications
the different elements they should be looking
at. So we set about defining the key areas that
we felt should be considered in the design of a
successful architecture.
Firstly, we need to look at the ‘70’ in the
70:20:10 learning model. As 70% of the way
we learn is said to come from experience, we
need to make sure we are building dialogue,
coaching and mentoring opportunities and
communities into our learning architecture.
This may include everything from forums
through ‘ask the expert’-style communication
channels, to popular social media platforms,
allowing your audience to share knowledge and
engage with each other in different ways.
Secondly, we need to create the right
content, in terms of knowledge resources and
learning resources, and make them accessible
in the right way, to our audience. Knowledge
resources should be created to allow the
efficient delivery of just-in-time knowledge,
data or information. An appropriate blend of
learning resources should be also readied so
they are easily accessible at the most important
points of the learner journey.
We also need to think about deeper strategic
learning modes used in our architecture. The
most effective architecture will be based on a
range of modes to suit different learning styles
and which will help cement the transfer of
learning using multiple channels. Exploration
and discovery allows your audience to get
to grips with your learning or message at its
own pace. Audience members should then be
encouraged to test their knowledge or skills
with application activities, before participating
in reflection and reinforcement activities to
drive the message home.
Finally, we need to ensure our architecture
is sustainable. It is vital that you have a solid
engagement and communications strategy to
drive your initiative out to your audience. We
must also be prepared to carry out a thorough
evaluation to determine which elements of
our programme are working and where we
need to adapt them. Finally, look closely at
how your programme extends beyond the
core initiative – where can you capitalise on
the most successful parts of the architecture,
ensuring they integrate with other processes
and systems in your organisation?
By following this process to build a learning
and communications architecture in the
context of the business culture, we can be
CONSTRUCTION:
1. What do you already have in place?
2. What media do people respond to?
3. What is the appetite for innovation?
confident that we are setting ourselves up for
success.
An architecture for success
This is only a starting point. However, much like
an architect’s or builder’s checklist, which starts
with the planning permission and goes through
to choosing the taps, it will trigger the kinds of
questions that we believe you need to ask. Like
good building design, getting the mix right is an
art and a science combined, and not something
we should expect to achieve first time round.
However, by understanding the possibilities,
and using the foundations as a starting point,
we can expect to create a solid foundation for
an engaging architecture, which will stand the
test of time and provide a good place for
learning and communications to live. C
Glossary
70:20:10: The 70:20:10 framework states that
70% of our learning comes from on-the-job
experience, 20% from social learning and
10% from formal, structured learning.
References
Casebourne I, Tanner K (2014) The rise of multidevice learning Communicator Summer 2014,
pp48–51
Joly A, Tanner K (2014) A new future for learning.
Available:
http://leolearning.com/our-thinking (accessed
August 2014)
70:20:10 Forum (2014) The 70:20:10
Framework: what is it? Available:
www.702010forum.com/about-702010framework (accessed August 2014)
Andrew Joly is LEO’s Director of
Strategic Design, and is responsible
for guiding the overall strategy of
LEO’s learning initiatives and design
practices. He also created the concept
of learning and communications architectures.
W: http://leolearning.com
Tw: @acjoly
Kayleigh Tanner is a Marketing
Executive at LEO, writing about issues
in learning technologies and learning
design.
Tw: @DailyKayleigh
Marketing
Breaking into technical marketing
The demand is high and so is the pay. Cheryl Landes describes
more about technical marketing communications.
Are you a technical writer who enjoys telling
stories and evangelising about products
and services? Then technical marketing
communications is an excellent niche for you.
With the growth of content strategy and social
media, the demand for technical marketing
communicators is increasing rapidly. Salaries
for regular, full-time employees and hourly
rates for contractors are often substantially
higher than in most other areas of technical
communication because of the demand.
If you are interested in this field, what is it?
What types of work will you do? And, most
importantly, how do you break in? All of these
questions are answered in this article.
What is technical marketing communications?
Writers work closely
with all departments
involved in
developing,
promoting, and
selling the products
or services.
Technical marketing communications is all
about promoting a company’s products of
services of a technical nature. The goals of
technical marketing are to:
Sell a technical product or service to a target
market.
Promote the benefits of a technical product
or service.
Show how a technical product or service
is better than the competition.
Position a company as an expert in the target
market.
Where do technical marketing communicators work?
Where technical marketing communicators work
usually depends on the size of the company. In
small companies, technical marketing writing is
often an extension of a technical writer’s role,
especially if the employee is a lone writer. When
these companies are looking for candidates to
fill a technical writing role, they usually seek
someone with technical documentation and
marketing writing experience.
In larger companies, marketing or sales
departments hire full-time technical marketing
communicators. The marketing and sales
groups might be one department or separated
but still work closely together. The marketing
team focuses on promotion, while the sales
team focuses on selling products and services.
Technical marketing communicators
who are contractors are typically hired by
a marketing department or, if the company
is small, by the owner or vice president —
someone who is involved in promotion and
sales. Small companies tend to hire contract
writers on independent arrangements, while
larger companies request placements through
contract agencies. Occasionally large companies
hire independent contractors if their internal
policies allow.
Regardless of company size or employment
status, the writers work closely with all
departments involved in developing,
promoting, and selling the products or
services. The writers need to meet with
engineers or other subject matter experts
to gather information about the technical
aspects of the products or services. They also
need to work with the marketing and sales
teams to learn about the target audience and
understand the marketing and sales strategies.
From there, the writers create communication
materials for promoting the products and
services, and to help generate sales.
What types of materials do technical marketing
communicators create?
As mentioned earlier, technical marketing
communicators create any materials that help
promote and sell products and services. These
include:
Brochures. These are glossy, four-colour print
documents, ranging from one to four pages,
or beautifully designed webpages that focus
on either one product or service, or all of the
company’s products or services. Brochures
contain information about the company’s
background or experience related to the
product service, a description of the product
or service, the product or service features
and benefits, and a call to action. Sometimes
brochures also contain a complete or partial
client list.
Product data sheets. These printed black-andwhite sheets or webpages contain technical
details about a product. This information
includes a description about what the
product is and what it does, its features,
the technical specifications, how to main
the product, and the company’s contact
information. For electrical products, wiring
diagrams are also included.
Case studies. These brief reports, usually no
more than two printed pages or a webpage
not exceeding 450 words, tell a story about
how the company helped a customer solve a
problem with its products and services. Case
studies consist of four elements: a problem
statement, the company’s solution to the
problem, the results, and the benefits of the
solution. Often the benefits are repeated in
a sidebar to attract readers’ attention.
White papers. Similar to a position paper, the
white paper demonstrates that the company
35
36
Marketing
As technical
communicators,
most of us have
the basic skills to
become technical
marketing
communicators.
is an expert on a particular topic. White
papers may cover a company’s position
on a topic, reports on trends affecting the
company’s industry, or research results on
an industry topic. Some examples of white
papers I have written are: the differences
between measuring and metering airflow, and
the results of a series of tests conducted with
different cleaning agents to determine which
one was more effective in decontaminating
research laboratories.
White papers should not blatantly promote a
company’s products or services. White papers
favour the company in a subtle way. However,
since the early 2000s, more companies break
this rule in creating white paper content and
fully focus on their products and services.
Informational booklets. The information
booklets I have written are printed, either
fully four-colour or with a four-colour
cover and spot colour inside. (Spot colour
highlights certain graphical elements, such
as headings, sidebars, or objects in graphics,
with one colour throughout the document.)
Informational booklets provide details about
a product or service application. For example,
one of my projects focused on the different
types of airflow system configurations that
are used in a laboratory and the advantages
and disadvantages of each.
Newsletters. Most newsletters are now
electronic, circulated as emails to customers
and potential customers with updates about
products and services. Other newsletter
content includes company accomplishments
and events the company sponsored or
attended, and articles of interest related
to the company’s industry. Sometimes
newsletters publish tips on how to use the
company’s products. An example of this is
Kevin Siegel’s Skills and Drills newsletter1,
which contains a new tip every issue on how
to develop e-learning in Adobe Captivate.
Press releases. These are official statements
companies issue to the media with
information on a newsworthy topic. Some
examples are shown here:
New products or services
Product upgrades
Company anniversaries
Changes in company leadership
Financial forecasts and results
Sponsorships
Corporate takeovers, buyouts, partnerships,
or alliances
Response to public debate over an issue,
such as an accident at the company or a
food recall
Webpages. These can be website content,
blogs, or search engine optimised (SEO)
content. The goal of SEO content is to increase
1 Subscribe to this free newsletter at www.iconlogic.com
the company’s ranking in search engine
results.
Social media. Tasks include setting up social
media accounts and pages, monitoring and
posting content, and responding to posts and
comments. Marketing departments typically
assign these roles to a regular employee
instead of a contractor. Exceptions are when
companies hire marketing firms specialising
in social media to develop and maintain their
presence online.
Other materials. Examples are endless.
Other projects in which technical marketing
communicators might participate are:
Creating presentations for trade shows
and sales meetings
Developing training materials for special
customer workshops and events
Coordinating and hosting webinars
Writing scripts and recording videos and
podcasts
This long list may seem daunting, and obviously
you need a variety of skills to succeed in
technical marketing communication.
What skills do technical marketing communicators
need?
The good news is, as technical communicators,
most of us have the basic skills to become
technical marketing communicators. The most
important skills we need are transferable:
Communicating clearly and concisely in
writing and verbally
Learning and understanding new information
quickly
Knowing where to find information
Being flexible and willing to change in a fastpaced environment
Knowing how to target information effectively
to its intended audience
Some may argue that technical marketing
communicators need more creativity than
technical communicators, but in reality,
technical marketing communicators are simply
using creativity in a different way. All writing is
creative, but the creativity methods we use will
vary depending on the particular writing genre
or even projects within a genre.
Now that you know you have the skills to
become a technical marketing communicator,
it is time to find some opportunities to use
your skills.
How do I break in?
Technical marketing communication
opportunities are everywhere, unlimited by
industry. If you do not have any experience in
marketing and are a regular employee, offer to
work on marketing related projects. Maybe the
company is working on a special project that
requires participation from cross-functional
positions or teams. Look for these and offer
to help.
37
Another option for gaining experience as
a regular employee is to offer to help your
marketing department with low-priority
projects that, because of other commitments,
no one has time to finish.
If you cannot work on internal marketing
projects, volunteer for a non-profit
organisation that needs help with marketing
projects. An example of a volunteer project
I completed five years ago is editing website
content for the Friends of Heybrook Ridge2
in Index, Washington, USA. This organisation
fought to stop developers from logging the
ridge where the town’s watershed is located.
Volunteers raised enough money so that the
organisation could buy the property, which
is now a recreation area and educational
centre. Although I had marketing experience
before helping with this project, I believed
in the cause and wanted to help. It also gave
me some fresh experience in environmental
writing, which is important to have for the
green industry, one of my target markets as
a consultant.
Bartering is another excellent method for
gaining experience. In the Pacific Northwest,
USA, bartering has grown in popularity
during the past 10 years. I barter selectively,
but the outcome benefits both parties. One
of my ongoing examples is a barter with a
guide service, where I maintain the mailing
list and create newsletters and flyers for
special events. In exchange, I receive free
outdoor trips.
Your goal is to accumulate writing
samples for your portfolio as proof of your
capabilities. A nice advantage of creating
technical marketing materials is that
most of the information is released to the
public, so you do not need to worry about
confidentiality issues during job interviews.
What is the future of technical marketing
communications?
Based on my observations, the demand for
technical marketing communicators will
continue to grow. On average, more than half
of my projects are marketing related, and I
expect that percentage to grow during the
next five years. All of my marketing projects
are virtual, which is another advantage when
schedule flexibility is required. As long as I
finish projects by the deadlines, my customers
are happy.
I have also seen more job postings for regular
full-time jobs that combine technical and
technical marketing skills. With the growth of
content strategy and social media, companies
are looking for candidates with a broader range
of skills. The more skills we have as technical
communicators, the more employable we are.
The future is full of opportunities, many of
which we cannot yet anticipate, and technical
marketing communications will be there to
promote these. C
2 www.heybrookridge.org
If you cannot
work on internal
marketing projects,
volunteer for a nonprofit organisation
that needs help with
marketing projects.
Cheryl Landes is an STC Fellow; the
owner of Tabby Cat Communications
in Camas, Washington, USA; and the
author of five books. Her specialties
are technical documentation,
marketing communications, findability, and
instructional design.
W: www.tabbycatco.com
Tw: @landesc
Localization Partner for your success
in Central & Eastern Europe
TRANSLATION
LOCALIZATION
DTP & MULTIMEDIA
ccess
[email protected]
+420 384 361 300
www.traductera.com
38
Customer experience
Advancing technical communication
Michelle Despres shares strategies for improvement by
applying principles from the field of customer experience.
CXPA a global nonprofit organisation
dedicated to the
advancement of
customer experience
management
practices.
www.cxpa.org
The likelihood
of organisations
initiating some CX
activity is increasing,
so it is beneficial to
be familiar with the
discipline.
Although aspects of the discipline have been
practised for some years, customer experience
(CX) is a relatively new profession. The Customer
Experience Professionals Association (CXPA) was
founded only three years ago.
I joined CXPA in its inaugural year, and since
that time, the profession has grown significantly.
Membership has almost doubled in the last two
yearsi. Sixty countries were represented at this
year’s conference (Temkin 2014). I’ve noticed an
increase in the number of CX articles in the press,
industries talking about CX, and CX jobs being
advertised. As the profession grows, those jobs
are becoming more granular. Whereas only 18
months ago, most positions were for managers
or directors of general ‘customer experience’,
positions now include experience designers, Voice
of the Customer managers, data analysts, and
customer intelligence directorsii.
The likelihood of organisations initiating some
CX activity is increasing, so it is beneficial to be
familiar with the discipline. While it’s not possible
to document that entire discipline here, I will
define CX, explain why it’s important, introduce
key concepts, and identify ways to integrate
technical communication and CX.
Strategies are based on my experience at CQG,
a software provider for the financial trading
industry. You may need to modify them based
on the size and scope of your organisation and
department, workplace culture, and availability.
Customer experience defined
CX is what customers think about an organisation
considering all of their interactions with it.
CX initiatives include two overarching goals:
Ensuring customers have the same experience
across the organisation regardless of which
department (silo) they interact with. Experience
is the sum of all interactions, so a breakdown in
one silo impacts the whole experience.
Ensuring the customer has a seat at the decisionmaking table. For example, there’s a question
on the table: ‘do we fix this software bug?’
The testing manager says ‘no’; no testers are
available. The customer says ‘yes.’ The question
should be one of resolving the testing resource
issue, not one of whether the bug is fixed.
The hope is that by accomplishing these goals, we
engage our customers. The customer engagement
process is illustrated in Figure 1iii:
The figure shows that first, customers must be
consistently satisfied. Note that a well-handled
negative experience is satisfactory. Consistently
satisfied customers gain confidence. Sustained
confidence is rewarded by loyalty. Loyalty leads to
recommendations, which leads to evangelism. Not
every customer graduates to evangelical zeal; the
goal is to advance as many customers as possible
as far up the pyramid as possible.
Managing CX is good business
Customer acquisition increases revenue; retention
drives down costs.
It’s the Age of the Customer. Customers have a
global audience, free tools to reach that audience,
and a strong sense of empowerment.
As competitive barriers erode, exceptional
experiences differentiate your organisation from
your competitors.
CX process and concepts
1. Map the customer journey
It’s the Age of
the Customer.
Customers have a
global audience,
free tools to reach
that audience, and
a strong sense of
empowerment.
Figure 1. The customer engagement process.
The customer journey is the path customers take
through your organisation. For example:
Journey at a clothing store: enter the store,
locate the department, browse the racks, try on
clothing, purchase clothing, exit the store.
Journey looking to hire a consultant: research,
inquire, hire, use, rehire.
Journey of CQG customers: discover, evaluate,
buy, use, rediscover, leave.
The expectation is that one successful step leads
to the next; whereas a negative trial experience, for
example, is not likely to lead to a sale.
When considering the customer journey,
make sure the customer is the subject of that
journey. Journeys framed from the organisation’s
perspective illustrate organisational experience,
not the customer’s.
39
The rediscovery phase of a journey may not be
obvious. Imagine you purchase a new car in April.
In November, you drive in snow for the first time
since purchasing the car, rediscovering the car.
Don’t neglect the end of the journey. Suppose
that as part of moving from one home to another,
you disconnect your cable or satellite television
service. If that experience is especially negative, you
may choose a different provider in your new home.
At CQG, our customers must sometimes cancel a
subscription before moving to another firm. Your
goal is for customers to choose you again.
interaction points in several journey phases.
CQG’s journey will illustrate.
Discover and Evaluate: Publicly available
documentation may be seen by potential
customers; we can help make a good first
impression.
Use: Help systems, user guides, and job aids
are used by existing customers.
Rediscover: Release notes expose new features.
Customer experience
process:
Increase your interaction with customers to improve the
experience
1. Map the customer
journey
2. Identify interaction points
Use existing documentation in a new way.
Interaction points occur at times when customers
interact with organisation personnel, processes,
and artefacts (physical items). They are also called
‘touch points’. For example:
At a hotel, you interact with the front desk
staff (people) during check-in (process). You are
sometimes asked to sign a form (artefact), and
you are given a key (artefact).
A customer researching consultants may look
at a website (artefact), phone the consultant
(people), and ask for a quote (process).
You should strive to state interactions from the
customer’s point of view. ‘Customer receives
invoice from independent consultant’, not
‘Consultant sends invoice to customer’. The
importance of this distinction becomes apparent
in the next step of the process.
At trade shows, offer quick reference guides.
Use quick reference guides as a sales tool.
For example, the CQG Spreader quick
reference guide illustrated the robustness and
sophistication of the trading product and also
demonstrated the extensive customisation
possible, qualities important to customers
looking for a spread trading application.
2. Identify interaction
points
3. Identify pain points
Pain points are negative experiences and create
unnecessary obstacles. For example:
A restaurant host seats you at a table and states
that your waiter will be right with you. Twenty
minutes later, the waiter has yet to arrive.
An independent consultant misses a deadline.
Interactions stated from the organisation’s point
of view lead to pain points experienced by the
organisation, not the customer. A customer
receiving an invoice is a different action from a
consultant sending an invoice.
Figure 2 shows the process through this step.
3. Identify pain
points
4. Create listening
posts
Create new documentation.
Reuse content to create guides specifically for
software trials (Hughes 2012).
Fill gaps and enhance customer education
materials. For example, trading symbolism
can be tricky. CQG could ask its customers to
rely on industry sources for industry-specific
information. Instead, we offer a comprehensive
guide that defines strategies, explains how to
read a strategy formula, instructs how to create
a strategy formula, and lists all of the strategies
currently available to trade with CQG.v
Encourage the discovery of new product
features. In lieu of release notes, I introduced
the WIIFY (What’s In It For You). Instead of only
listing changes to the software, the document
explains the benefits of new featuresvi. Instead
of release notes focused on the product,
they’re focused on customer needs. Also,
details of what’s new in that software version
are automatically displayed in the software
following upgrade.
State interactions
from the customer’s
point of view.
4. Create listening posts
Listening posts are customer feedback
mechanisms positioned at different parts of the
journey. Voice of the Customer improvement
programmes depend on qualitative and
quantitative feedback. For example:
A store receipt includes a number to call to
provide feedback of the shopping experience.
A website prompts you to take a survey.
A consultant asks customers how likely it is
that they would recommend the consultancy’s
services. An organisation’s Net Promoter
Scoreiv is based largely on the response to that
question.
Know where you are in the journey
Technical communication products can provide
Figure 2. Customer journey at CQG.
40
Customer experience
Support other departments.
Instead of release
notes focused on the
product, focus on
customer needs
Customers abandon
websites that do
not answer their
questions
We have a broad skill set, including analysing
tasks and audiences, assessing usability, creating
graphics, interviewing, understanding technical
information, and writing, that can be used across
the organisation.
Assist with crisis messaging. Instead of ‘sorry
for the inconvenience’, you can provide a clear
explanation of the issue, a statement of how the
issue is immediately being addressed, and some
reassurance it won’t happen again.
Find other channels for your work. Provide tips
and tricks for inclusion in your organisation’s
external newsletter. Share content of particular
interest to customers on your organisation’s
blog.
Contribute to creating internal and external
training through content reuse or instructional
design.
Suggest product improvements.
Write and edit for other groups. I have worked
with groups across the organisation, including
business development, compliance, finance,
human resources, and office management.
Besides being of help, my participation
increases mutual understanding of the work we
do and how the organisation operates.
Teach. Create templates for customer emails,
checklists for style guides, and tutorials for
developers writing user interface text and
error messages. Work with marketing to create
a voice guide. Some of us are native English
speakers working with teams of people whose
first language is not English. Share grammar
and usage tips, or write a column for the
internal newsletter.
Eliminate pain points
Identify and resolve technical communication pain points.
Give customers the
opportunity to help
themselves rather
than rely on support
Of course, speaking with customers directly is
one of the best ways to identify pain points, but
there are others.
Talk to colleagues who work directly with
customers. I made sure to interview colleagues
in different groups, offices, and countries for a
more complete picture.
Monitor internal support tickets, which are
often recorded in a database that can be
queried.
Add your name to email distribution lists. I
read support emails to test the documentation.
For each question, I look for the answer in the
Help file. If it’s not there or difficult to find,
that’s a pain point in need of resolution.
I also instructed our support team to assign
all requests for documentation to me. Not
only does it increase customer interaction
and save support time, but it also ensures
that customers do not receive outdated
documentation saved on a local drive.
Read social media.
Perform an online search, even if your
organisation is small or has a niche product.
I found customers in trading forums.
If your organisation has its own customer
forum, participate.
Once you know what technical communication
pain points exist, work to resolve them. My
article in Communicator, Summer 2014 details
my work with pain point resolution (Despres
2014).
Be aware that not all pain points can be
resolved within the boundaries of your
department. In your research, you are likely
to find pain points that include more than
one silo. For example, customers receiving
outdated documentation is a pain point shared
by technical communication and support.
Resolution requires a joint effort.
Help with other pain points.
You may be able to eliminate pain points not
directly related to your group but that require
your skillset: writing procedures, creating
graphics, and designing education. Consider
these pain points across the journey:
Website discoverability is often a pain point.
Your knowledge of information architecture
and content strategy could be shared with
less experienced colleagues. In the ‘discover’
phase of the journey, discoverability is crucial.
Customers abandon websites that do not
answer their questions. Additionally, you can
help colleagues view the website as a support
tool as well as a sales tool.
Managing the trial process is important
because it directly impacts sales. You don’t
want to be intrusive, but you also don’t want
your customers to feel abandoned. With the
trial process team, craft messaging for new
users. Links to your documentation can be
included in the welcome letter, so customers
are given the opportunity to help themselves
rather than rely on support. This independence
is particularly beneficial if you have customers
around the globe and support staff who are
not available 24 hours a day.
Pain points are sometimes caused by
confusion, as a result of complex processes,
dense information, a multitude of variables
to consider, or interwoven relationships.
Information design can help alleviate
that confusion, improving the evaluation
process tremendously. Perhaps some of that
information can be expressed in graphics
rather than in words that require fluency in the
language.
Some industries require that contracts be
completed during the purchase process.
Help the sales team write clear instructions
for completing those agreements, so that
customers begin the process with a positive
experience.
With the customer’s first bill, include a graphic
of the bill with callouts for important features.
41
For organisations that charge for service a
month in advance, an explanation of the double
charge is helpful.
Many ‘use’ pain points can be addressed
with education. At CQG, we created detailed
instructions for our customers to optimise
their systems for maximum performance.
Additionally, we linked to those instructions
from our trial letter. That way, customers had
this information before using the system, and
we reduced the chance of issues due to less than
optimum system performance.
You may assume customers don’t need
installation instructions for software, but they
do need to know about quirks of the system.
Also, operating systems, settings, and software
compatibility changes. Support may assist
customers who call, but we can create the
documentation that results in fewer calls.
Get feedback
There are various common feedback channels for
Help systems. CQG’s Help system also includes
an email link for ‘Questions for the Help Author’.
You should also know where customers stumble
or have questions, so suggest other listening
posts.
Ask if you can attend customer events, go along
on visits, or observe training.
Request that testing program managers include
questions about documentation.
Disseminate documents using social media.
Add a feedback button to software.
Recommend that potential customers be
surveyed at the end of the trial period.
Suggest the establishment of a customer
council or advisory board.
Suggestions for department leaders
CX work happens at the domain level as well as at
the task level. Department leaders can:
Incorporate CX competencies by framing
projects and processes according to customer
interaction rather than by silo, thereby shifting
the focus from independent functions to the
collective experience.
Talk about customers in all of your meetings;
explain data; share positive feedback.
Work according to a brand promise, either at
the organisational or departmental level.
Hire, train, appraise, and recognise for
CX. ‘Hire the attitude; train the skill’ is a
sentiment repeated throughout the literature.
For a permanent position, why require
tool knowledge, thereby eliminating from
consideration exceptional communicators who
don’t happen to know a particular tool?
Understand customer behaviour.
Empower direct reports to solve issues.
CX is good for technical communication
CX is beneficial not only for customers but also
for us.
CX encourages us to refocus on customers.vii
CX expands the scope of our work, resulting
in greater responsibility and additional
opportunities.
CX provides occasions to employ secondary
skills: synthesis, problem solving, creativity,
and relationship building.
CX strengthens workplace relationships
through cross-functional team participation.
CX increases our visibility and value.
Technical communicators fluent in CX principles
possess business knowledge outside of their
specialised domains, making them valuable
resources for any organisation. C
Hire the attitude;
train the skill
Resources and Further Reading
CXPA (2012) CXPA Announces 18 Finalists for CX
Innovation Awards (online) available from: http://c.
ymcdn.com/sites/www.cxpa.org/resource/resmgr/
Docs/cxpa_may_31_2012.pdf (accessed July 2014)
CXPA (2014) Countdown Starts to CXPA 2014
Insight Exchange Event in Atlanta, May 13–14
(online) available from http://www.cxpa.
org/?page=pr_20140507 (accessed July 2014)
Support may assist
customers who call,
but we can create
the documentation
that results in fewer
calls
Despres, M (2014) ‘Refocusing on the customer’,
Communicator, Summer 2014: 40–42.
Golding, I, UK CXPA Ambassador,ijgolding.com
Hughes, M (2012) ‘User Assistance that Influences
Sales: Writing Help for Software Trial Versions’,
WritersUA conference presentation
Hyken, S (2009) The Cult of the Customer: Create an
Amazing Customer Experience That Turns Satisfied
Customers Into Customer Evangelists, Wiley, New
Jersey.
Temkin, B (2011) Customer Experience Overview:
Q&A on the Customer Experience Market. Available
from http://www.cxpa.org (accessed December
2011)
i 1400 in May 2012, 2700 in
May 2014 (CXPA 2012 and
2014).
ii From my own survey of CXPA
Temkin, B (2014) CXPA update by Bruce Temkin, 2014
Insight Exchange (online) available from http://
www.cxpa.org (accessed July 2014)
member emails sent from
January 2013 to June 2014.
iii My synthesis of ideas from
Shep Hyken (2009) and Bruce
Temkin (2011).
iv Net Promoter Score (NPS) is
a standard CX metric. See
Michelle Despres, MA is Director of
User Assistance and Customer
Experience Advocate at CQG, a
software provider for the financial
trading industry. Previously, she was a
senior technical writer for Carlin Financial Group (now
RBC Capital Markets) and NASDAQ. Michelle is a
member of STC, CXPA, and ATD.
http://en.wikipedia.org/wiki/
Net_Promoter
v www.cqg.com/Docs/
ExchangeTradedStrategies.
pdf.
vi www.cqg.com/
Docs/13.4GeneralWIIFY.pdf.
vii “For many of us, a majority
of our time is spent within
the organisation’s physical
and virtual environments.
Many, if not all, of our
daily interactions are with
colleagues. Organisational
Chrissy Kimball, MS is Adjunct Professor of
Communications at Southern Connecticut State
University and owner of Sasstastic Designs, an
independent design company. Previously, she was US
Interactive Media Manager for PAREXEL International,
a clinical research and medical communications
company. She provided the images for this article.
priorities may demand most
of our attention, if only
because those priorities
occupy our immediate field
of vision. If we do not actively
shift our focus, our vision
can become imbalanced,
especially under pressure”
(Despres 2014).
42
Verbal skills
Training in verbal skills
Jean-Paul Bardez looks at how you can improve
your verbal communication skills.
Technical communicators fulfil information
needs that were never expressed, supplying data
which was never written before.
The best data management system will never
provide technical communicators with this
information, it has to be collected in verbal
form. Neither will the system manage all aspects
of a documentation project, solve technical
issues, suggest product improvements after
documentation has been tested by clients, etc.
What did you say? You don’t test? I see... So you
need to convince your boss this validation step
is required; to verbally discuss documentation
with your clients. For several years now, I have
been teaching these verbal skills, which I find
central to our roles as technical communicators.
This article provides a few examples of the
exercises I use.
Producing good documents requires oral
proficiency, a skill that can help in some
typical situations such as: persuading in
meetings, informal discussions in the elevator,
a chat during a coffee break or lunch, making
suggestions for alternatives in follow up
meetings, collecting information when
interviewing engineers or clients, requesting
additional information or raising issues when
discussing with the project leader, on the phone,
through videoconference, etc. If we want to
produce good quality output, we must speak up
in a variety of situations, and clarify facts with
engineers several times during each project.
Address people fluently
As a first exercise, I ask students to make a three
minute presentation of a concept to special
recipients (elderly, blind people, telepathic extraterrestrials, etc.) with precise quality criteria, and
a shift in the concept to explain, this enables a
playful approach. It can lead to self-assessment
which always comes as a surprise since the
outcome is... good marks. And how could it
be different? The criteria for self-assessment
is known, we all tend to respect the special
recipients without making a special effort.
This exercise has several purposes:
getting students to talk in a situation,
building up self-confidence by proving to
students that they are able to communicate
verbally,
establishing a group atmosphere based on
observation,
putting the emphasis on oral communication,
making students use notes as a help for
verbal performance and recording what they
hear,
making students understand how easy it is to
communicate once the communication goal
has been clearly defined, and
finally, making a first approach regarding the
topic of verbal skills.
Take full advantage of the richness of the word of
mouth
Words fly away, writings remain. We don’t
organise debates for the sake of verbal jousting.
Debriefing the first assignment gives us the
opportunity for a first verbal group exercise,
and this must be given special care. Several
students are therefore asked to report on
specific aspects of the group talks, like “What
differs from a school approach?”, “What helps
change?”, “What is unusual?”, etc. It is about
building on the density of oral information by
using « filters » and taking notes. At the end of
the debate, we have a round table discussion,
to enable each participant to speak and express
what they found useful.
This feedback enables me to fine tune the
workshop, and it also places the students in a
position where they act on their own training,
and at the same time get used to discussing as a
regular activity.
Personally, I take many notes on what I hear
in an interview context, be it formal or in front
of the coffee vending machine. The transition
from speech frees my memory and prepares
information for later use when I will need it for
writing. During group discussions, I always ask
several students to take notes so that they are
able to later produce quick verbal feedback.
This way, we go back and forth between speech
and text and students get accustomed to be
actively listening, and to giving a greater value
to the unwritten information.
Provide evidence
We, as technical communicators, are often
asked to provide evidence that our role needs
to cross enterprise boundaries, and that just
rewriting functional specifications will not
suffice. The first document to create is a user
satisfaction survey. Even if we have a sense for
spotting weaknesses in a document, the only
valid proof is customer feedback. So I train my
students to set up user satisfaction surveys.
Quickly adjust processes based on talking
The best way to make clothes fit is to adjust
them. The same concept applies to writing. In
order to design surveys, students interview
users, to identify problematic areas. Asking
43
users questions and validating the survey with
them enables us to quickly set up a relevant
survey. Online tools ease the production of the
survey and process the results very easily. The
students see the gap between user information
needs and what they have been provided with.
Reflecting on this experience is part of the
process and students get accustomed to take
some distance with the written document.
Reliable and relevant information exists, but
technical communicators need to learn how to
collect it.
Be fluent
One of the first assignments we practise is to
ask trainees to test a user noting particulary
how they use a function of a smart phone. In
order to do that, students rehearse a scenario
telling people taking part in the test that it
is not they who are being tested but the user
instructions and we’re interested in what the
customers don’t understand. They learn and
rehearse this scenario like a play, because
it must be identical for everyone tested, to
provide homogeneous test conditions, and so
that students get into the habit of rehearsing
important verbal dialogues. We ask testers to
speak aloud what they think. Students write
down their customer feedback to process it
later and improve their user instructions.
It is the first contact students have with an
iterative approach to documentation. It is also
the first opportunity to abandon their natural
resistance to edit text they have written, if they
understand that the real value they add is not
to produce a text (which will never compete for
any literature prize), but to make it comply with
the users’ information needs.
Steering meetings using minutes writing
Monitoring meetings? Usually, nobody
volunteers to write meeting minutes. The
person writing them needs to ask questions
to be able to report on the decisions. Discuss
documentation requirements with engineers,
sales people and management to discover the
problematic areas which are likely to negatively
impact on the documentation process. Asking
questions and rephrasing what has been said
often makes the project move forward.
Get confident with technical communication basics and
convince
In order to become an expert, you need to know
about the profession history, and the available
tools. Rather than lecturing on technical
communication, I prefer having students work
in small groups to synthesize documents on our
profession or on tools, before presenting it in
verbal form to their fellow students. This way,
we produce once more “spoken instructions
to explain”, I can monitor what students really
understand of the major issues on technical
communication, and we can then discuss them
in order for students to acquire substantive
arguments and have them readily available for
future discussions.
Train to convince
Convincing others is an art which requires you
to consider the other party’s position. You only
convince others if you are convinced yourself
of the position you are defending, and if you
can give concrete examples. Since we tested the
documentation of a smart phone function, we
play “we must test our documentation” scenario
and make video recordings, which we view to
find improvement paths. This approach is very
similar to the ones used to train sales people.
Other verbal tools
The spoken word offers many more
possibilities. I suggest students read aloud their
written production, to detect improper language
use, lack of fluidity and repetitions. I also
advise them to read their text starting from the
last paragraph, in order to better spot spelling
mistakes which we see better when the text we
are reading does not make much sense (as is the
case when we reverse read it).
For all these reasons...
Verbal proficiency of the students, their ability
to rephrase on the fly, to find a sense to the
product they are documenting, to keep in mind
the documentation target and to question,
convince, also to accept their production to be
challenged by their recipients, all these are
undisputable assets for future technical
communicators, and they must be trained in
them. Of course our trade also requires written
proficiency and mastering information
technology tools, but to my mind, writing ability
and computer literacy are a long way from being
enough to make a good technical
communicator. C
Jean-Paul Bardez is a highly
experienced writer and translator of
user documentation with over twenty
years of solid experience. As a
freelance consultant he has assisted
many clients in the software and telecommunications
industry. He is the founding President of the French
society Conseil des Rédacteurs Techniques and
TCeurope’s current President. He has been teaching
Technical Communication at Clermont-Ferrand
University for the past four years.
W: www.bardez.com
44
Leadership and management
Facilitate towards agreement…
John Crawley continues to support John Burns to reflect on his
journey using mediation as a vital tool in the manager’s kit bag.
The mediator needs
to exhibit behaviours
and an air that
engenders rapport.
In the Summer 2014 issue of Communicator, John
Crawley and John Burns added to the leadership
and management series with an article discussing
mediation. We now revisit this topic and series
with part 2 and discuss the idea of the joint
session. This is the forum where parties in dispute
come together and take part in a structured
discussion that the mediator facilitates.
Essentially, this is where mediation happens.
This is the meeting that builds on the planning
and separate party discussions, explained in the
aforementioned article, which brings parties face
to face to move from argument to agreement.
As part of his continuing journey to further
develop his mediation skills, John Burns (JB),
in the second of three parts, introduces the
concepts and practicalities of the joint mediation
session. This is again mentored by leading
expert John Crawley (JC) – mediator of 25 years’
experience, published author and the man to help
John Burns learn to facilitate towards agreement!
Brief recap…
In our previous article we spoke of meeting
with the disputants on an individual basis, to
describe the process and its inherent protocols
and steps. This preparatory step is to manage the
expectations of the parties in dispute and inform
them of what happens in the joint session.
The curtain falls…
The mediator
must avoid
rapport-destroying
behaviours.
So, we have held the individual meetings with the
disputants but now the curtain falls and we move
into the joint session, starting with preparing the
environment.
Step 2: The joint mediation session: opening
2.1 Preparing the mediation room
JB recognised the need to identify a comfortable
room where interruptions can be minimised
if not completely avoided; however, he tells
Communicator:
Figure 1. Mediation stages
‘before studying and practising mediation I
didn’t realise that there are many subtleties,
not necessarily self-evident, that can bias the
process.’
JC adds further:
‘The room should be neutral and avoid
offering any advantage to either party.’
In other words, a room could contain a religious
artefact such as a picture, an allegiance to a club/
society or the layout of furniture could indirectly
prejudice the session, as it may be perceived to
benefit one party more than the other.
2.2 Welcome and introductions
As the step suggests, this is where the mediator
welcomes each party to the joint session.
Although this sounds fairly straightforward it
is an extremely important part of the process.
In addition to creating a positive tone and
atmosphere, Crawley (2012) states: the mediator
must adjust their vision and body language to
accommodate and acknowledge both parties.
2.3 Getting the parties to trust you
Given that the mediator wants and needs parties
to be open, express their feelings and share
information (Crawley 2012), this of course can
only really take place in a background of trust
and integrity. While JB realised this he adds:
‘when learning about mediation I needed
prescriptive advice as to how to foster trust
and provide an environment where each party
would open up and help me understand their
point of view, articulate this to the other party
and provide a platform to attempt to move to
agreement.’
JC helped by adding:
‘The mediator needs to exhibit behaviours and
an air that engenders rapport… encouraging
parties to make their own decisions about
what they choose to speak about and showing
respect for both parties.’
While the above is helpful, JC added further value
45
by explaining the behaviours to avoid when trying
to foster trust. He also adds (Crawley 2012) that
the mediator must avoid ‘rapport-destroying’
behaviours. Specifically, the mediator must:
avoid using statements that are value-laden;
providing inaccurate interpretations of each
party’s behaviour; forgetting what has been said
and must avoid a patronising or condescending
approach.
2.4 Uninterrupted time
This is an exceptionally important aspect to the
mediation process as uninterrupted time is, in
theory, the opportunity that each party receives
the time to air their views, concerns, issues and
so on. The mediator fosters this environment,
and supports this through the protocols for
mediation, to enable each party to have the
confidence that they receive their turn to speak.
As Crawley (2012) states, the party that is
awaiting their turn to speak should be actively
listening at this point and indeed the mediator
should mention this although, of course, is
unable to guarantee that will happen.
During this step the mediator has to start the
process and ask the first party to begin. Here the
mediator asks them to summarise their issues,
stating that this will assist all to understand how
they are feeling.
2.5 Getting the first party started
This is essentially where the mediator asks one of
the parties to speak and encourages them with a
friendly, welcoming tone.
2.6 Encouraging parties who are quiet
Sometimes the mediator can experience parties
that are quiet, both in tone and/or what they are
saying. In this instance, Crawley (2012) provides
guidelines to draw people out. This could be
simply asking something you feel they may
be comfortable answering. For example, when
mediating between parties from a professional,
workplace setting, the mediator could ask
someone about the nature of their job, length of
service and then move towards speaking about
the problem in a progressive and gentle manner.
JC further supports this, though adding:
‘The mediator can even directly make the
observation that a particular party is quiet
through a statement such as… I see you are
very quiet and am really interested to hear
what you are thinking…’
In the pursuit of providing each party with
an equal opportunity for speaking it is very
important for the mediator to create these
openings within the session.
2.7 Steering the second party
This step is a very interesting point and one that
can be very subtle for those new to mediation. JB
realised this and added:
‘Although it seems obvious now, I didn’t really
Step 2. The joint mediation session: opening
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8
2.9
Preparing the meeting room
Welcome and introductions
Getting the parties to trust you
Uninterrupted time
Getting the first party started
Encouraging parties who are quiet
Steering the second party
Protecting uninterrupted time
Summarising each party’s
uninterrupted time
Copyright John Crawley (2012)
consider initially that while the first party
speaks during their shielded time, the second
party could well be combusting at this point
and itching to speak!!’
JC helped by adding:
‘The mediator needs to be gentle but robust
in directing the second party, reminding them
that their turn is coming and to concentrate on
their point of view as opposed to getting drawn
into a conflict.’
2.8 Protecting uninterrupted time
As hinted at earlier, in theory the shielded time
provides, as its name suggests, an exclusive
window for a party to express their issues and
concerns. However, of course, the party that is
meant to listen can actually interject… JB has
experienced this and added:
‘Although I knew this was a possibility,
like many aspects of life, it isn’t until you
experience it that you realise it can be
common; moreover, a mediator definitely
requires strategies to address it!’
JC again assists JB by saying:
‘The mediator will sometimes need to
control such a situation through gentle
encouragement. This may be through asking
the party speaking out of turn to pause,
acknowledging that they’d like to respond but
reminding them it is the other party’s time and
that they will receive their opportunity.
2.9 Summarising each party’s uninterrupted time
This is the final stage of the opening to a
mediation session. As Crawley (2012) states, this
is where the mediator summarises the issues and
how each party is feeling and importantly what
outcome each party is aiming for. Once this has
been achieved, the session moves into a phase
where the parties directly communicate with each
other.
The mediator needs
to be gentle but
robust in directing
the second party
and thus avoiding
conflict.
The mediator has to
convince the parties
that they can find
a common ground
for a structured
discussion.
From monologue to dialogue?
While the opening of the session presents its
challenges, requiring skills and awareness,
it is perhaps this phase that is the liveliest
and requires a sound understanding of, and
the ability to apply facilitation techniques
or understanding how to follow a process to
46
Leadership and management
Step 3. The joint mediation session: dialogue
3.1
3.2
3.3
3.4
3.5
3.6
3.7
Starting and sustaining dialogue
Watching out for the seeds of resolution
Encouraging responses
Getting feelings heard by both sides
Crystallising detail
Transmitting information
Getting the parties to notice new
information
3.8 Structuring the discussion
3.9 Handling difficult behaviour
3.10 Preventing withdrawal
3.11 Pulling everything together
Copyright John Crawley (2012)
structure a discussion or meeting (Mann 2014).
This phase contains many steps and is
complex. They are presented as an overview here,
but are discussed in detail in John Crawley’s
Argument to Agreement (2012).
Mediation is often difficult because in addition
to parties exhibiting aggression, frustration
and impatience there is sometimes a more
fundamental issue. Crawley (2012), remarks that
it is often difficult for the parties to agree about
what the problem actually is. In the absence of
such an agreement, the mediation session is
almost rendered futile. To this end JB enquired to
JC, what can the mediator do in this context?
Mediator-led clarification
JC remarked: mediator-led clarification! This is,
as its name suggests, a phase that the mediator
introduces to clarify the position, to achieve
commonality of issue, to form a platform, and to
move from argument to agreement.
To achieve this there are three main skills that
Crawley (2012) recommends:
Mutualising
Normalising, and
Bridging summary.
Mutualising
In short, the idea behind mutualising is feeding
back to the parties, areas that they have in
common as opposed to the areas that they
disagree on. Crawley (2012) speaks of an example
where there is a workplace dispute and the
mediator provides a general common ground to
drive towards finding a mutal understanding; for
example, ‘I can see you are both under pressure at
the moment…”. This also has the advantage that
it does not require a response from the parties.
Normalising
Crawley (2012) adds that statements that
normalise are those that make generalisations
about a situation or experience that are relevant
to the parties’ situation. Continuing the example
of a workplace dispute, a mediator may use a
normalising statement such as: ‘working with
someone new can be very challenging – I can
see how this can be difficult to start with.’ This
is a general statement that acknowledges the
situation can be difficult without discussing the
minutiae of the issue.
Bridging summary
The bridging summary technique is a way that
the mediator can progress the discussion using
a summary that is factual. In terms of our
workplace conflict example, the mediator would
try and remove the current impediment in the
discussion and provide summaries such as:
‘Thank you both for your directness
and honesty. It will help us to progress the
conversation if I summarise both your accounts…
Peter… you are busy and would like an outlet to
be able to delegate some work; Dave, you are also
busy and want a regular meeting with Peter to
discuss priorities…’.
Once the mediator has fed back using these
techniques, it is important for each party to
confirm whether anything has been omitted.
Provided that both parties are content with the
summaries, feel they are accurate and agree on
the common ground, the mediation can continue.
Step 3: The joint mediation session: dialogue
Once the parties have agreed on a common
theme, that is, they agree about what they
disagree about, the mediator can begin to engage
them in direct dialogue.
Like other phases of the mediation process this
contains a number of steps.
3.1 Starting and sustaining dialogue
In this step, the mediator needs to identify and
agree on an issue that the parties agree they
should discuss. Here, the mediator should ask
the parties to look directly at one another if their
eye contact slips.
3.2 Watching out for the seeds of resolution
Here, the mediator needs to listen actively and try
to identify anything, within the discussion, that
has a seed of resolution – something they can use
to find commonality between parties. Building on
our previous example…‘So Peter, you did intend to
prioritise the work for Dave but didn’t get round
to it…’. Here the mediator knew that Dave wanted
a meeting to discuss prioritisation and Peter
has mentioned that he acknowledges a meeting
where this needs to be discussed.
3.3 Encouraging responses
Often, particularly in the beginning of sessions, it
seems that parties are running in parallel and not
really moving towards agreement. Here a mediator
can foster or encourage responses through the
application of a variety of ‘encouraging phrases’.
For example: ‘Thanks for saying that Dave, could
you be more specific?’; ‘Thanks Peter, could you say
more about that to Dave?’
47
3.4 Get feelings heard by both sides
Here the mediator facilitates the parties and
provides an environment where they hear one
another, both positive and negative. Within this
step the mediator can consider using re-framing:
a technique to change a communication so
it may be more palatable or receptive to the
recipient.
3.5 Crystallising detail
During mediation sessions there are many
fragments of information that each party will
possibly bring to the table. Here the job of the
mediator is to provide a structure and make
sense of this array of information. This could be
through a number of techniques such as asking
questions to assist with clarification to chunking
information to help with its consolidation and
arrangement. As Crawley (2012) states, many
parties want to dwell on the past; the mediator
only needs them to focus on the past to enable
them to move forward into the future.
3.6 Transmitting information
While mediators of course remain impartial, they
are responsible for channelling or transmitting
information. Specifically, as Crawley (2012)
states: the mediator needs to vocalise all the
important information as positively as possible.
Again, this may involve a reframe to express
something more appropriately.
3.7 Getting parties to notice new information
During a typical mediation session some new
information emerges and it is often these
fragments of information that the mediator can
use to help the discussion along. JB asked JC,
what sort of approach you can adopt here. JC
adds: in our example of the conflict between
Peter and Dave we could say:
‘Dave… may I check, did you hear that… Peter
admitted his latest work list was distributed
without priorities…’
3.8 Structuring the discussion
This concerns arranging the discussion,
particularly with a view to what area the session
focuses on. Furthermore, good mediation also
manages those areas that are impossible to
mediate; that is, areas where an issue cannot be
changed or lies outside the sphere of authority
of those people in the room.
3.9 Handling difficult behaviour
Dealing with difficult situations, personal
interactions and so on are something that
could fill an article in its own right. However,
Crawley (2012) does speak of a continuum of
interventions from a gentle approach through
to coercion. The recommendation is to move
between the gentle approach to something
assertive without a fully coercive approach.
As an example, JC points JB to:
Ask for a change in behaviour
Recall the suggested change, and
Request the change to progress the mediation.
3.10 Preventing withdrawal
There are many ways in which one or both
parties can withdraw from a conversation; for
example, from not talking, to changing the
subject, or focusing on the past. In this instance
there is a variety of approaches the mediator
can use, as outlined in Crawley (2012), to get the
session back on track. For example: ‘Dave… how
is that relevant to today? Can we focus on the
future? Or ‘Peter… could you stay with us for the
agreed time?’
The mediator only
needs to get the
parties to focus on
the past to enable
them to move
forward into the
future.
3.11 Pulling everything together
This step is essentially a summary phase before
things move forward into the next stage. Here
the mediator will summarise proceedings thus
far and clarify what has been agreed, the focus
areas and delineate those things that are out
of scope; that is, impossible to resolve through
mediation.
References
Where are we in our mediation journey?
In this article we built on our work in the
previous issue of Communicator, where we
spoke about a mediator’s preparatory work. This
current piece has moved into the joint discussion
phase, where we have talked about preparing for
these meetings and the initial stages, where each
party faces one another and gets to hear what
the other is saying. These are essential steps that
precede the topic of our next article: The
Movement – moving from individual positions to
agreement. C
John Crawley is an author, speaker,
trainer and international consultant
with an acknowledged reputation for
designing systems to resolve disputes
and other types of conflict in
organisations. Recognised as the leading creator of
accredited training materials for mediators in the UK,
he was the principal consultant on the BBC Worldwide
training video on managing conflict at work.
E: john.crawley@peopleresolutions
W: www.peopleresolutions.com
John M A Burns is an IT manager
leading a team that develops and
supports a range of systems within
the ICT Division at Solihull MBC. He is
an experienced project manager,
ISEB-qualified business analyst, systems developer
and holds a postgraduate qualification in Technical
Authorship. He has conducted facilitated meetings
for private, public and third-sector organisations. He
holds an OCR certificate in Mediation Skills.
Burns JMA and Mir
A (2013) ‘Permission
to abstain from
decisions!’
Communicator,
Summer 2013:
34–37
Crawley J and
Graham K (2011)
Mediation for
Managers: The Skills,
Step-by-step Process
and Management
Style for Getting
Beyond Conflict
to Performance,
Nicholas Brealey
Publishing
Crawley J (2012)
Argument to
Agreement –
Resolving Disputes
through Mediation
(Pocket Guides to
Conflict Resolution)
Amazon
Crawley J and
Burns JMA (2014)
‘Help reading the
mediation map…’
Communicator,
Summer 2014:
33–35
Mann T (2014)
Facilitation Develop
Your Expertise, RP
Publishing/APMG
High Wycombe
48
Markdown
A tool that even your developers will use
Raymond Gillespie considers the pros and cons of lightweight
markup languages as tools for technical documentation teams.
Lightweight markup languages, such as
Markdown and reStructuredText (reST), are
increasingly popular for creating web-based
technical information. For example, the
documentation for the Python programming
language is written using reST, while flavours
of Markdown are used for the GitHub and
Stack Overflow sites popular with developers.
These languages enable you to format text
elements, such as headers, lists and code
fragments, in a similar but more minimalist
way to HTML. The formatted text is easy to
write and easy to read.
In this article, I will talk about one of these
lightweight languages, namely Markdown,
which is a particularly simple and elegant
language developed by John Gruber. I will
show how easy it is to create technical
content with Markdown. Then I will discuss
some advantages and disadvantages of using
a lightweight language such as Markdown for
creating technical content compared to using
a semantically richer language such as Darwin
Information Typing Architecture (DITA).
Getting started with Markdown
There are many excellent tools available for
writing Markdown. For this example, I am
using Markdown Pad, which runs on Windows.
A good tool for the Mac is Mou and for Linux
ReText.
One nice feature of Markdown Pad is that
it has a two-pane interface, and as you write
your Markdown in the left pane, the rendered
HTML is previewed in the right. So let’s get
started by looking at the examples shown in
Figure 1. A step-by-step procedure written in Markdown
Figures 1 and 2. To try these examples out,
install Markdown Pad and simply type the
text into its left panel.
These examples make use of the following
Markdown elements:
1 Headings. Precede your heading with hash
marks; one hash signifying heading level 1,
two hashes heading level 2 and so on.
2 Numbered lists. Precede each list item with
a number followed by a full stop.
3 Code block. Indicate code blocks by
indenting each line by at least four
characters (commonly one tab stop). For
a code block within a numbered list – like
that shown in Figure 1 – indent each line by
at least 8 characters (two tab stops).
4 Inline code. Wrap inline code with backtick
characters (`).
5 HTML tables. The basic version of
Markdown does not have its own syntax
for tables. However, you can easily create
tables by inserting standard HTML tags.
6 Hyperlinks. You can create hyperlinks by
putting the link text in square brackets
followed by the URL in parentheses.
For a comprehensive list of the available
Markdown tags, see
http://daringfireball.net/projects/markdown/
syntax
Should I use a lightweight markup language for my
project?
The simplicity and minimalism of
lightweight languages such as Markdown
comes with a price. And that price is
that they lack the semantic richness of
49
Figure 2. A reference table written in Markdown
a heavy-duty language such as Darwin
Information Typing Architecture (DITA).
Using Markdown and DITA as examples, in
the following sections, I list some of the
advantages and disadvantages of using a
lightweight language for creating technical
documentation.
Advantages of Markdown
Markdown is a text format that is easy
to both write and read. It can be edited
using any text editor. Thus project team
members are free to use their favourite
editor.
Since Markdown files are simply text files,
the documentation can be stored along
with the code using the same file version
control tools as the development team (see
Figure 3).
This can be advantageous for software
projects that require a lot of input from
the development team. For example, say
your project requires that an Application
Programming Interface (API) has to be
documented. By using Markdown, you
could adopt a simple workflow where the
programmer can write initial drafts in
Markdown using their favourite text editor
and then commit those files to the version
control system they are already using for
their code. A technical communicator can
then check out those files for editing.
After further rounds of updating and
editing, the files can be reviewed using the
same processes and tools as are used for
reviewing the code files.
The tools needed for editing and versioning
Markdown files are inexpensive and most
likely already available to the development
team. In contrast, good-quality DITA tools
tend to be more expensive. This can result
in situations where only specialist technical
communicators are provided with DITA
editing tools. This makes collaboration
between technical communicators and
engineers much more difficult.
Markdown is easy to learn. Thus the entire
team can learn the tool and be up and
running in only a few hours.
Disadvantages of Markdown
Compared to DITA, Markdown lacks
semantic information. With DITA we can
make use of semantic tagging to do things
that cannot be done with Markdown such
as the following:
Differentiate between different types of
topics, for example the three basic DITA
types: task, concept and reference. DITA
tools and templates make it easy to
create consistent topics of each type.
Using attributes, identify elements
that should only be published when
particular conditions are met. For
example, we could have conditional
steps for the Mac, Linux and Windows
versions of the software we are
documenting.
Markdown is not designed for easy content
reuse. With DITA, we can reuse a topic in
various deliverables simply by including a
reference to the topic’s ID in a ‘DITA Map’
Figure 3. Using the Tortoise SVN versioning tool to show the difference between
two versions of a Markdown document
50
Markdown
file. There are also DITA mechanisms such
as conref and keyref for reuse of smaller
components such as warning texts. None of
these reuse mechanisms are available with
Markdown.
Although great for quickly writing short
chunks of information, Markdown shows
its shortcomings once you start to use
it for large documents. Since there is no
equivalent to a DITA map file, creating
a structure for a large document in
Markdown, and maintaining hyperlinks
between the related sections takes a lot of
manual work.
By contrast, with DITA tools, once you
have your maps and sub-maps created
for a complex document, the links
between related topics will be managed
automatically.
What about auto-generated documentation?
In this article, I’ve been examining both
Markdown and DITA through the spectacles
of a traditional technical communicator,
from the viewpoint of one who collects
information from the development team, and
writes up that information in a form easily
digested by the users.
However, there is another approach,
namely to auto-generate documentation from
the software code – an approach particularly
suited for API documentation. Ed Marshall,
in a two-part article on documenting APIs
spanning the Autumn and Winter 2012 issues
of Communicator, states:
“...Running automated tools provides
a major benefit over documenting
these products the traditional technical
communicator way in that you are generating
your documents from a ‘single source of
truth’.”
It is well worth reading Ed’s article to get
an insight into the tools and challenges
involved with creating auto-generated
documentation.
A commonly used tool for generating
documentation from Java code is Javadoc.
It can generate descriptions of public
classes, the code classes that you are
making available to your customers via
an API. It will generate such things as the
names and return values of methods, data
types of parameters and such like. You can
add more detailed documentation – such
as descriptions of classes, methods and
parameters; example code; and links to
other parts of the documentation, by writing
specially formatted comments in the code.
Another tool, Doxygen, can do a similar job
auto-generating documentation from other
languages, such as C, C++ and Python.
When using tools such as Javadoc and
Doxygen, the onus is normally on the
developer to write the documentation
comments in the code. But as Rachel Potts
points out in her article from the Summer
2013 Communicator:
“...developers are capable of writing good
content, but they are necessarily involved in
thinking in detail about small parts of the
application.”
This can lead to documentation that “...
lacks the ‘big picture’ perspective.”
In other words, document-generation
tools are great for producing reference
information such as descriptive lists of
classes and methods exposed by an API,
but are less suitable for creating higherlevel documents such as overviews, getting
started guides, and tutorials.
However there are ways to combine both
approaches and include your high-level
documentation in the code. For example,
Doxygen now supports Markdown, so you
could conceivably write your conceptual
and instructional information directly into
the code as Markdown. Similarly, Rachel
Potts in her article describes docfacto, a
very interesting tool that extends Javadoc
to make it more friendly for writing quality
documentation. It allows inclusion of code
examples and simple SVN graphics, and
even provides validation of the embedded
documentation (for example to identify
public methods and parameters that
haven’t been documented). One other nice
feature of docfacto is that it enables the
documentation to be generated as DITA
files. This results in a possible workflow
where you combine auto-generated and
writer-generated DITA files to create a
comprehensive documentation set.
Conclusion
Choosing a lightweight markup language
such as Markdown makes a lot of sense
for documentation projects that involve a
lot of collaboration between the technical
communicators, software developers and
other members of the product development
team. The tools required for writing, editing
and versioning the documentation files are
cheap and are most likely already available
to the development team. What is more,
languages such as Markdown are easy
to use and are more likely to be used by
non-technical-communicator team members
than a more complex approach such as DITA.
However, this simplicity comes at a price.
If you are working on a documentation
project that requires large documents,
consistent use of different topic types,
extensive content reuse and conditional
publishing, you might be better served
selecting a more heavy-duty approach such
as DITA.
51
Additionally, when deciding on
documentation tools and processes for your
project, you need to consider the use of a
tool such as Javadoc, Doxygen or docfacto
to generate documentation from your code,
especially for the creation of reference
information about API classes and methods.
Whatever approach you take – whether it
be to write your documents manually in
DITA or a lightweight language such as
Markdown; to auto-generate your
documentation using a tool like Javadoc,
Doxygen or docfacto; or
to use a combination of manually created
and auto-generated documentation – the
underlying necessity is that you, the
technical communicator, get close to the
development team. Only together can you
choose the approach to creating
documentation that will best suit your
technical communicators, your developers
and your product management in achieving
the shared goal of creating great software
supported by great documentation. C
Raymond Gillespie MISTC has 20
years’ experience in the field of
information technology. For the past
14 years, Raymond has lived in
Budapest, Hungary working as both a
software engineer and a technical writer, mainly in
the fields of telecommunication, medical imaging
and navigation software. He holds an MSc in
Information Management from Lancaster University
Management School (UK).
References and further reading
Markdown editors
Markdown language
MarkdownPad (Windows)
http://markdownpad.com/ (accessed 7 July 2014)
Markdown syntax
http://daringfireball.net/projects/markdown/syntax
(accessed 7 July 2014)
Mou (Mac OS X)
http://mouapp.com/ (accessed 7 July 2014)
Example sites using lightweight markup languages
GitHub
https://help.github.com/articles/github-flavored-markdown
The GitHub code versioning site allows its users to post issues,
comments, and ‘pull requests’ (proposals to collaborate on code
stored in a particular repository) using a flavour of Markdown.
Python documentation
https://docs.python.org/devguide/documenting.html
The lightweight language reST is used for creating the Python
programming language documentation.
Stack Overflow
http://stackoverflow.com/editing-help (accessed 7 July 2014)
Programmers can post questions and answers using Markdown
on this site.
ReText (Mac OS X)
http://sourceforge.net/p/retext/home/ReText
API documentation practices and related tools
Docfacto
http://docfacto.com (accessed 3 August 2014)
Doxygen
http://doxygen.org (accessed 3 August 2014)
Javadoc
www.oracle.com/technetwork/java/javase/documentation/
index-jsp-135444.html (accessed 3 August 2014)
Marshall, E (2012) ‘Breaking into a specialty market: part 1’
Communicator, Autumn 2012: 36–36
Marshall, E (2012) ‘Breaking into a specialty market: part 2’
Communicator, Winter 2012: 24–28
Potts, R (2013) ‘Docfacto improves software documentation’
Communicator, Summer 2013: 24–27
$UH\RXDQH[SHULHQFHGWHFKQLFDO
FRPPXQLFDWRU"
7KH,67&SURYLGHVDPHQWRULQJVFKHPHIRULWVMXQLRUPHPEHUVPDWFKLQJWKHPZLWKDWHFKQLFDOFRPPXQLFDWRUZKRKDV
H[SHULHQFHLQHLWKHUDVLPLODURUFRPSOHPHQWDU\DUHD
2XUPHQWRUVDUHDOO)HOORZVRU0HPEHUVRIWKH,67&ZKRDUHNHHQWRVKDUHWKHLUNQRZOHGJHDQGH[SHULHQFHZLWKQHZHQWUDQWV
WRWKHSURIHVVLRQ:H¶UHDOZD\VORRNLQJIRUDQ\RIIHUVRIKHOS±HYHQLI\RXFDQRQO\VSDUHVRPHWLPHWRRIIHURFFDVLRQDO
JXLGDQFHVD\IRUDVSHFLILFWDVNRUVNLOORULQWHQVLYHFRDFKLQJEHIRUHDQLQWHUYLHZ
,I\RXDUHDPHPEHURIWKH,67&DQGZDQWWRILQGRXWPRUHDERXWWKHPHQWRULQJVFKHPHFRQWDFWWKH,67&RIILFH
LVWF#LVWFRUJXN
ZZZLVWFRUJXN
52
Product review
Scroll add-ons for Confluence
Thinking about using Confluence for Content Management?
Nils Bier reviews Atlassian Confluence and the add-ons available.
Content was around long before content
management, in the stories that stone-age
people told each other round the fire, for
example. By sharing their knowledge and
traditions by word of mouth, they helped their
tribe to survive and gradually improve their
quality of life. However, as time went by, some
of that information would have been altered,
or lost altogether.
Eventually, people began to record and
preserve their knowledge and experiences –
initially in cave-wall paintings. Later on, monks
became the very first content strategists,
writing down the stories told by the common
people on scrolls of parchment or paper. This
made it far easier to bring them to a wider
audience.
By the 20th century, knowledge had
become an increasingly valuable resource for
manufacturers and many other organisations.
More and more enterprises began to preserve
and manage their internal knowledge assets
and make them accessible to their employees,
in the form of manuals, memos, bulletin
boards, and later, digital media. In corporate
environments, social communication tools
such as wikis play a similar role to those
ancient camp fires.
However, modern content strategists, like
the monks of old, are faced with the problem
of content that is unstructured, yet potentially
extremely useful.
An enterprise wiki such as Atlassian
Confluence is an excellent tool for collecting,
managing and controlling access to
knowledge company-wide. And it’s a major
step forward for technical communicators,
because it puts an end to the problem of
vital knowledge existing only in the experts’
heads. Collaboration platforms of this kind
have become the camp fire of today in the
sense that they support intuitive sharing of
corporate knowledge between colleagues, in
virtual teams, and even with business partners
and customers. Confluence is complemented
by add-ons for specific use cases, including
content management.
The Scroll Content Management add-ons
enhance Confluence’s out-of-the-box
functionality to meet the specialised needs of
technical communicators. These needs include
versioning, translation, document exporting,
to name but a few.
Atlassian Confluence: company-wide collaboration
on a single platform
Confluence is a collaboration platform
developed by the Australian enterprise
software company Atlassian. The first version
of Confluence was released back in 2003
as a wiki solution for enterprises. Over the
years, Confluence has expanded its functional
scope and its user base, evolving from a mere
enterprise wiki into a collaboration platform
used by companies across the globe.
Confluence comes with all the capabilities
needed to work on content collaboratively:
your co-workers, key knowledge holders,
engineers, developers, and any other
subject matter experts can easily store their
knowledge in a single, shared system. They
don’t have to be Confluence power users or
attend week-long training courses. Thanks to
the intuitive rich-text editor (Figure 1), there’s
nothing stopping them from getting started
and making entries.
Confluence can be used in a host of different
ways: as a knowledge base, for internal
communications, as an intranet platform, and
as the CMS that hosts your website.
At K15t Software, we use Confluence for
all our documentation work. For instance,
our human resources team creates new
employment contracts, maintains the
employee manual, and records meeting
minutes in Confluence. Our developers create
software specifications and document best
practices in our internal knowledge base. Our
consultants work with customers via our wiki.
And finally, our technical communicators
manage product documentation there.
Adding technical documentation capabilities to
Confluence
Figure 1. The Confluence rich-text editor
Now you know a little more about Atlassian
Confluence, I’d like to offer you deeper insight
into the Scroll Content Management add-ons
53
and how to use Confluence effectively for
technical documentation.
Let’s imagine that your organisation is
already using Confluence, and everyone is
happily sharing their knowledge. Once the
content is in the system, it’s your job as a
technical communicator to make it readable,
improve the style, and visualise, structure,
review, version, translate, and distribute the
content.
“Hmmm, that’s quite a long list of
requirements for a collaboration platform,”
you might well be thinking. True, but let’s not
forget the Atlassian Marketplace and the Scroll
add-ons I mentioned earlier.
Make your content available offline
K15t Software was founded about five years
ago as a part-time project with the aim of
making Confluence content available offline.
We wanted to enable users to export their
content in a visually appropriate style with
just a few clicks.
Since then, we have launched six Scroll
Exporters for Confluence content that extend
the tool’s built-in exporting functionality:
Scroll Office
Scroll PDF Exporter
Scroll HTML Exporter
Scroll EPUB Exporter
Scroll EclipseHelp Exporter
Scroll DocBook Exporter.
All Scroll Exporters conform to the principles
of single-sourcing: by creating a template
and what’s called an Export Scheme, you can
define exactly what your content will look
like when it’s exported. The content itself is
completely separate from the style, so the
same content can be published to a variety
of formats. You can define multiple Export
Schemes for a space, to make them available
to a defined group of users. Or you can define
them globally and let all your users employ a
given Export Scheme.
In addition, all our exporters support
REST, which enables the latest exports to be
obtained automatically. For those who practice
continuous integration of their software, the
Scroll Exporters’ REST interface is a great
help when it comes to consistently including
the latest documentation in nightly builds. It
makes it easy to trigger an automatic export of
your documentation.
Many of our customers use a Scroll Exporter
to export their Confluence content to the
target format they need: EPUB for service
engineers out in the field, who have no reliable
access to the internet, or PDF for printing and
physically archiving technical documentation
to meet compliance requirements, to name but
two of the export formats supported.
Our Scroll DocBook Exporter has already
been employed to publish whole books that
were created by a team of authors and editors
working entirely in Confluence.
Develop your product and its documentation at the
same time
Developing your product and working on
the documentation at the same time in
Confluence is no longer a risky proposition,
thanks to Scroll Versions. With this add-on, it’s
possible to work on multiple versions within
a Confluence space and provide the right
content in just a few clicks when you’re ready
to ship the product. Versioning functionality is
something that many technical communicators
have been eagerly awaiting.
It’s especially popular with agile software
development teams because it enables
technical communicators to keep pace with
rapid release cycles. Shorter release cycles
leave less time to work on documentation, and
so Scroll Versions is an ideal tool for working
on the documentation and the product in
Confluence concurrently.
Scroll Versions 2.0 saw the introduction of
variant management functionality. Whereas
previously it was only possible to version
content, users can now document similar
products in the same space. This means
that content can be re-used and all relevant
information maintained in a single space.
REST
(REpresentational
State Transfer) is
a simple stateless
architecture that
generally runs over
HTTP.
Internationalise your Confluence content
As more and more organisations go
global, they need to provide product
documentation in multiple languages, which
Figure 2. The documentation lifecycle
54
Product review
presents yet another challenge for technical
communicators. Confluence lacks out-ofthe-box functionality for managing multiple
languages. Scroll Translations bridges the gap
between translation management systems
(TMS) and Confluence. It lets you manage
multiple languages in the same space.
Depending on your use case, you can choose
between two different approaches:
On the one hand, Scroll Translations lets
you translate your content in Confluence
itself. When selecting a target language in
the language picker, the Confluence page’s
“Edit” button becomes a “Translate” button,
and you can directly translate your content
there.
Of course, that’s not feasible when you
have thousands of pages of content. So
Scroll Translations also lets you export
your content in XML format, give it to your
translation service provider or import it to
your TMS, translate the contents there, and
re-import it to your Confluence system.
Improve the quality and consistency of your content
1 Abel, S and Bailie A (2014)
The Language of Content
Strategy XML Press
Entering content is one thing. Improving its
quality and ensuring consistent style, voice,
and tone is quite another. The more people
are involved in content creation, the more vital
these issues become.
That’s where content optimisation software
such as Acrolinx comes in. By defining
grammatical rules, term sets, expressions, and
phrases, you can take control of the writing
style used throughout your organisation,
even if dozens of writers are involved. When
automated checks have been performed,
authors can pick the desired word or phrase
from the suggestions offered by Acrolinx in
line with its built-in rule sets or corporate
terminology resources. In this way, you can
make your corporate content clearer and
easier to understand, and eliminate the errors.
And greater consistency makes it simpler and,
therefore, cheaper to localise or translate,
content.
In an open platform such as Confluence,
where everyone is invited to contribute, it’s
even more important to ensure consistent
wording and style rules. Until now, wiki
users have had to rely solely on browser
functionality or browser plug-ins to check
spelling and grammar. And they had no way to
check terminology or evaluate content quality
using metrics.
With the Scroll Acrolinx Connector add-on,
Confluence users can reap all the benefits
of Terminology Management at the same
time. The Scroll Acrolinx Connector helps
Confluence authors to speak with one
voice throughout their organisation. The
Connector is already being used by several
global enterprises to check and improve their
Confluence content. With this add-on, they
are able to check compliance with any writing
rule and terminology set in their authoring
environment, the Confluence editor.
Each Confluence page displays a content
quality score that reflects compliance with the
organisation’s language and style guidelines.
And to gauge and monitor the space’s overall
content quality, the add-on provides a status
dashboard that displays quality metrics at
a glance and enables users to see detailed
assessment results for each Confluence page.
If content is king, design is queen
Confluence is a really good platform for
creating and managing content. It offers a
number of options for theming and styling
content, but because its primary focus is
content creation, it doesn’t provide much
support for customising the way content is
presented. Once again, K15t Software fills the
gap: this time, with Scroll Viewport.
Up to now, this article has been about
creating content. But when you make it
available to your target group, you’ll want
to present it in the best possible way, with
style. With Scroll Viewport, you can define
viewports to deliver your content faster,
more easily, and in visually attractive ways.
You can create templates in plain HTML, CSS
and JavaScript, and take full control of how
your content is presented to different target
audiences. As a result, Confluence can be
employed as a CMS, and can also be the basis
for your website or your intranet. Lastly,
everything is in the same system: from the
earliest drafts and ideas, to the structured
documents ready to be presented to the
customers.
Scroll Viewport and Confluence were
recently used to collaboratively create
the website and content for the book, The
Language of Content Strategy1. One advantage
of employing Confluence for collaborative
book authoring is that all participants work
in a user-friendly wiki, rather than having
to learn DocBook. This frees them up to
concentrate fully on the content.
But, of course, the book is also available
online. Using Confluence and Scroll Viewport,
it’s possible to publish the same content on
the web, but in a suitable style and layout for
a website. This looks completely different to
a wiki!
As the book consists of 52 chapters,
one chapter is automatically posted every
Thursday. Enough content for a whole
year, written collaboratively by 52 different
authors, and published using Confluence.
Part of the book’s content strategy was
to enrich the web output with additional
content, such as audio files and graphics not
included in the printed book. All additional
55
resources are stored and managed in
Confluence, which serves as a single source
for content of all kinds.
A wiki for creating technical documentation: can that
really work?
That’s a question we’re asked from time
to time. “It depends,” is probably the best
answer. There will always be use cases and
organisations for which a wiki is not the
best-fit solution, regardless of all the thirdparty add-ons available to customise and
extend the tool.
Confluence’s approach is to get everyone
involved in content creation, and to provide an
easy-to-use platform for documentation. Some
organisations have workflows that are too
complex for this approach. Others are obliged
to produce heavily structured technical
documentation that can only be maintained by
XML-trained technical writing experts.
However, a wiki such as Atlassian’s
Confluence is a genuine alternative to the
established heavyweights in the technical
communications space. There are now many
organisations, from large corporations
to start-ups, who love the flexibility and
simplicity of Atlassian Confluence, but also
need the content management capabilities that
our Scroll products provide. More important
than an organisation’s content management
requirements is how enthusiastically it
embraces the wiki-based approach to
managing content and collaboration.
All of an organisations’ knowledge base is
maintained on a single central system and
accessible to all. Confluence is the focal point
for all information resources, contributors and
users. It’s where today’s knowledge workers
share their experience and insights.
InfoPlus+
Each month the ISTC
distributes information, news,
advertisements and details of
events relating to scientific
and technical communication
through InfoPlus+. It keeps
you up to date with local area
group news. There are listings
for training courses,
exhibitions, conferences and
meetings in the UK and
worldwide. Find out what’s
happening in your region and
read about social networking.
Conclusion
Today, everyone can take on the medieval
monk’s knowledge-recording responsibilities.
And wikis such as Atlassian Confluence are
the modern equivalent of the scroll. Scroll
add-ons from K15t Software enable Confluence
users to manage content more efficiently, and
encourage everyone to take part in the
process. C
References
Acrolinx
www.acrolinx.com (accessed August 2014)
Confluence
www.atlassian.com/software/confluence (accessed
August 2014)
The Language of Content Strategy
http://thelanguageofcontentstrategy.com
(accessed August 2014)
Nils Bier is Technical Communicator
and Customer Advocate at K15t
Software. K15t Software is building
tools and solutions based on
Confluence that make working on
documentation easier. Their tools for wiki-based
documentation extend the wiki approach to work for
technical documentation, project and process
documentation and to involve traditional office users.
W: www.k15t.com
Tw: @k15tsoftware || @nilsinger
B: https://blog.k15t.com
It’s free to subscribe
The electronic newsletter is available to everybody, so if you would like to receive
notification as soon as it’s published, send your details to the [email protected]. You
can view past copies online at www.istc.org.uk/our-publications/infopluswww.istc.org.uk/our-publications
/infoplus-newsletter/
newsletter/
Do you provide training courses relating to technical communication?
Are you organising an event?
Send us your course or event details and dates. Take a look at past editions to see
the format. If you want to promote a particular course or event in more detail – why
not send us an article too?
Please send all submissions to: [email protected].
Advertising
Advertising in InfoPlus+ can help you achieve greater brand awareness and
exposure with target readers. This is particularly useful if we are publishing a related
article. While editorial coverage is not dependant on advertising in the newsletter,
our advertising representative might contact you to see if the benefits of a paid
advertisement appeals to you. If you are interested in advertising in the newsletter,
contact Felicity Davie: [email protected].
56
Case study
SideKick: every author’s assistant
An appraisal of the latest software development from Ovidius by
Carsten Regehly, at Schnell Motoren AG.
Have you ever worked with XMetaL Author
Essential?
XMetaL Author Essential by JustSystems
is part of my content management system
(CMS). It is the XML/SGML editor that enables
me to create and edit documentation that
is stored in the CMS, TCToolbox (developed
by Ovidius). There are a number of positive
reasons for using the XMetaL Author
Essential:
Configuration is quick
It’s easy to use, even for those with little to
no XML knowledge
The system is robust
JustSystems provides powerful APIs
The price.
Around my documentation system I have
other third-party systems that contain
information that I have to use within my
documentation.
These other systems can include spareparts systems, software development
systems, CMSs and of course my XML CMS.
JustSystems provides powerful APIs to
assist in connecting different systems. I
approached Ovidius and asked them how
they would solve the problem.
API Connector or not?
Their answer was that they could build one
or more system connectors (see Figure 1),
but I would have to be aware that there are a
number of potential problems.:
Whenever the API of the third-party system
Figure 1. To API or not to API?
changes, the connector needs to change.
Furthermore, the third-party system may
not be available at all times due to network
or maintenance issues.
Finally, you may not be allowed to access
third-party systems at all for a number of
reasons.
Ovidius suggested a data-centric interface
instead: an XML interface structure is
designed, which is used to relay the relevant
information from the third-party application
to a companion product that communicates
with XMetaL. Any third-party application
can export the data, either directly into the
XML structure or into any other documented
structure (for example, an Excel spreadsheet
or any other XML structure) which in turn
is transformed into the interface structure.
SideKick is the companion product and was
developed for this purpose. This article is an
introduction to the tool and the principles
behind it.
Linking the Spare-Parts Catalogue
Schnell Motoren AG has been developing
combined heat and power (CHP) units for
efficient and sustainable energy generation
from biomass since 1992. As the production
process modernised we have incorporated
various data systems for efficiencies. For the
sake of this article I have chosen to focus on
the Spare-Parts Catalogue. Within the SpareParts Catalogue there are parts with names
and numbers. The names are sometimes
ambiguous but each spare part has a unique
ID number that enables the engineer or
service technician to differentiate one from
the other. Within our documentation the
technical author references the spare part
with a special XML element. The spare-part
ID is coded as an attribute on that element.
The author uses spare-parts references
especially when describing maintenance
procedures containing instructions on how
to insert, extract or service the part. Before
we had SideKick, I would enter the data
manually. It was necessary to manually
select the attribute tag, search for the spare
part in the catalogue and then enter the 7- or
8-digit number. There was plenty of room
for error with that workflow and I was very
happy to receive an alternative.
SideKick behaves as the middle-man
between XMetaL Author Essential and
my third-party system with no need for a
specially built system connector (see Figure
57
2). I only need a new configuration with
each new machine or product I have to
document. This is easy enough since I get
that information anyway from development
or sales (list of relevant spare parts, list of
GUI strings, and so on. ).
SideKick is a data connector that receives
information in a simple, well-documented
XML format. It enables the author to insert
that information into the document in
XMetaL Author Essential as either a reference
(that is later clickable in an electronic
publication) or as hard data.
Benefits
This approach, using a data-centric interface,
is beneficial as all of my third-party systems
can provide me with an XML export that I
can easily synchronise with the configuration
in SideKick. The referencing process
becomes automated and because SideKick
is so flexible it is possible to design or
conceptualise any number of tabs holding
different types of information that I could
require for my authoring. That includes
templates, variables, small, re-usable text
fragments, and metadata, for example, for
configuring variant information, target
groups, and so on.
The fact that I can add pre-configured
information into XMetaL with a single
click has reduced my processing time
significantly. I can add variable paragraphs,
include XML elements with complex values
and paste templates with the click of a
mouse. SideKick has reduced my workload
considerably. Additionally, I have all of the
information where I need it. For especially
large amounts of data (I sometimes have
more than 20,000 spare parts to consider),
SideKick has a built-in search or filtering
function that helps sort through the
information efficiently (see Figure 3).
now, there is only a tiny error message in
the bottom-left corner that I discovered
only after it was pointed out to me, which
can be frustrating. The other suggestion is
that when I want to place a warning within
the document, I am only shown the XML
structure of the element in the SideKick
GUI. I would, however, like to see the whole
warning, or at least have a colour code for
‘danger’, ‘warning’ and ‘caution’ to be certain
I am using the correct one as they are all
quite similar.
In the future I would also like to do my
own configuration for new data types. The
interface XML-structure is documented well
enough that everybody with some basic XML
and XSLT know-how can take almost any
third-party export data structure and feed it
into the SideKick configuration.
Figure 2. Sidekick: a data-centric interface
Adoption
In the beginning there were a few things to
get used to. The initial installation was a
bit difficult. I had to contact support to get
it sorted out, which was resolved quickly.
When checking a module out of the XML
CMS, I had to ensure that it was within the
context of a manual to receive only the
context-related configurations that I wanted,
or else I was shown all of the information
available in the system, which was confusing
at first.
Since working with the tool, I have raised
some suggestions that the developers at
Ovidius have taken to heart. The first is
that when an invalid position is chosen for
an element, I would like the information
in SideKick to be greyed out so that I have
no option but to find a new position. Right
Figure 3. Spare-Parts list in SideKick
58
Case study
Final thoughts
All in all I find this little tool to be an
unbelievable relief for the editor. By
choosing a data-centric instead of a
system-centric approach to interfacing
between systems, I have gained several
benefits. SideKick is a really lightweight
connector between several of my third-party
applications and XMetaL. I can configure it
myself if needs be without programming
experience, and I am not worried about
changes in APIs, availability of third-party
systems or restrictions on system access.
Ovidius is one of the largest suppliers of
XMetaL licenses within Europe and is
available for consultation and configuration
of SideKick and XMetaL, regardless of the
CMS you use. C
Resources
JustSystems (2014) XMetaL
http://xmetal.com (accessed August 2014)
Ovidius (2014) TCToolbox 7
www.ovidius.com/files/pdf/140611-TCT7_A4_
EN-2.pdf (accessed August 2014)
Carsten Regehly has worked in the
field of technical documentation since
2001, and is project manager for the
development, supervision and
analysis of data and interfaces for
generating product and spare-parts catalogues (data
and drawings) at Schnell Motoren AG, Germany.
W: www.schnellmotor.de
Translated by Rebecca Newton, Social Media Marketing
Coordinator, Ovidius GmbH.
Tw: @EvylAppel
The Ovidius Social Media Channels:
Tw: @OvidiusGmbH
LI: www.linkedin.com/company/ovidius-gmbh
B: http://blog.ovidius.com
MadCap tips
The MadCap column
In this regular column, Matthew Ellison, explains some of the
issues relating to importing from Microsoft Word into Flare.
Most Flare authors will need at one
time or another to import content
from Microsoft Word into Flare. I am
asked about this issue more frequently,
perhaps, than any other aspect of
Flare. There are two main scenarios
that may require you to import from
Word: the first is that you have legacy
content (perhaps a previous manual
that was written in Word) that you
need to convert to Flare. In this case,
it will be a one-off import and you
will be discarding the Word document
following the successful conversion.
The alternative scenario is that a
subject matter expert is creating and
maintaining content in Word format
that you will import and link to your
Flare project. In this scenario, you will
want to repeat the import process each
time there is a change to the Word
document, and the corresponding
topics in Flare will be updated. This
article describes the import process in
more detail, and explains the important
differences between the ways in which
you should carry out the import for
each of these two scenarios.
How does the import process work?
The process of importing Word
documents into Flare is controlled by
a special XML (.flimp) file within the
Flare project. This file is called an MS
Word Import file, and you can create
it either by using the Word Import
Wizard (Project > Import > MS Word
Documents) or simply by adding a new
MS Word Import file to your project and
configuring it using the Word Import
Editor. This file specifies the names
and locations of the Word document(s)
to be imported, and various settings
that control how the incoming Word
Table 1. Risks and issues that make projects complex
Source: Agile Project Management (2012) DSDM Consortium.
Tab
Setting
Recommendation
Source
Files
Link
Generated
Files to
Source
Files
Select this option only for scenario 2 where the content
will continue to be updated in Word. As a result of selecting
this option, Flare will display a warning message each time
you attempt to edit any of the imported topics. This is to
avoid changes in Flare being over-written by re-importing
from Word.
New Topic
Styles
‘New Topic
Styles’
Select heading styles (Heading 1, Heading 2, etc.) to break
the document into short, self-contained topics. The level of
heading that you need to go down to depends on the size
and depth of the source document.
Options
Autoreimport
before
‘Generate
Output’
Select this option only in scenario 2 when you have linked
the generated files to the source files. Flare then checks for
changes to the original Word document each time you build
a target, and re-imports the entire document if it finds any.
Be aware that any edits you have made to the corresponding
topics within Flare are over-written without warning.
Stylesheet Source
Styles
Paragraph
styles
I always select ‘Don’t Preserve MS Word Styles’. This strips
out any manually-applied formatting and enables me to
map the Word styles to the styles in my Flare Stylesheet
(which I select from the drop-down list on this tab). In
scenario 2, if the Word document is heavily reliant on
manually-applied formatting and you are not planning
to edit the topics in Flare, then you may choose to select
‘Preserve MS Word Styles’.
It is not possible to map Word’s list styles to Flare’s list
styles, so I leave these unmapped. This results in the bullets
and numbering being preserved. I’ll describe how to deal
with the imported lists in next issue’s column.
document is segmented into topics
and styled. After completing the Word
import process, in the case of scenario
1 (one-off import) you would have no
further use for the Word Import file
and you could delete it. For scenario 2,
it is important to retain the MS Word
Import file because it will be required
each time you need to refresh the
topics in Flare with updated content in
the Word document.
Preparing the Word document
Ideally the Word document should
be well styled and should not rely on
manually-applied inline formatting. It
should also be divided into ‘topic-sized’
sections by headings. Remove any
manual page breaks that may have been
applied (since Flare will treat these as
topic breaks), and also remove heading
numbering since this will be imported
in to Flare as ‘hard-coded’ numbers.
You should be able to do this quickly
and easily by modifying the heading
styles. Don’t forget to update the table
of contents (if there is one) to remove
the heading numbers from there.
What is the best way to configure the MS
Word Import file?
There is some debate about the
optimum settings to use, and the
recommendations I make for a small
selection of the most important
settings in Table 1 below reflect my
own personal preferences.
Other issues to watch out for
In my next MadCap column, I’ll describe
a number of features used in Word
documents that can potentially cause
problems during import, and I’ll explain
how to solve these issues through the use
of post-import clean-up techniques. C
Matthew Ellison MISTC
Eis an independent technical
communicator and consultant,
a Flare Certified Instructor, and
organiser of the annual UA
Europe Conference.
W: www.uaeurope.com
59
60
Ethical dilemmas
Real-life dilemmas
Warren Singer invites you to discuss true dilemmas
encountered by today’s technical communicators.
Life’s really like that! Technical
communicators often have to deal
with personal issues at work and
find solutions to dilemmas for which
their education or training may not
provide easy answers. These stories
provide examples of real-life problems
encountered by today’s technical
communicators.
What would you do in their situation?
After reading their story, let us know
how you would solve their dilemma.
The best responses will get published
in the next issue of Communicator.
Career progression
“Nick will be helping you on this
project.” Samantha, head of the
technical publications team, told Tim.
“I want you to show him what to do
and keep an eye out for him. Is that
okay Tim?”
Tim sighed and nodded. Nick was a
trainee technical communicator. Tim
was always asked to mentor new team
members.
Over the next few weeks Tim
showed Nick the ropes. He explained
to Nick the structure of the technical
documentation, went through the
company style guides and editing
standards, and introduced Nick to the
key stakeholders in their section of the
organisation.
Over the next few months, under
the watchful eye of Tim, Nick made
steady progress. Tim helped review
and edit the drafts that Nick produced.
Finally, Samantha asked Nick to take
over the responsibility for the projects
he was working on, and Tim was given
something else to do.
It was later that month that
Samantha announced that she would
be leaving and that a replacement for
the head of the technical publications
department would be recruited.
Tim sighed. He remembered
mentoring Samantha, two years
previously, when she had been a
newbie. At the time she had known
absolutely nothing about technical
communications: her previous role
had been as a low-level manager in
the customer services team of the
organisation. Tim had trained her
in the skills of being a technical
communicator. Then after several
months, she had been promoted to
head of the team. He had been quite
disappointed at the time.
This time, Tim decided to apply
for the role of head of the Technical
Publications team. Why not? He
was now in his mid-thirties, with a
young family and looking to move
ahead in his career. He had over
10 years’ experience as a technical
communicator and he had been
with this organisation for over six
years. He knew the company and its
products like the back of his hand.
He had personally mentored most
of the members of the team and,
over the years, had created most of
the core content for their technical
documentation suite.
At the job interview for Samantha’s
position he met with André, the VP
of technology, who would be the
manager of the new head of technical
publications, and with Leiya, the HR
executive who was managing the
recruitment campaign.
At the start of the interview, André
looked at him sharply, then spoke. “So
tell me Tim, why do you think you are
suitable for this role?”
There was something slightly
dismissive in the tone that made Tim
hesitate. The look had been a little too
direct and the question too impatient,
as though André believed that Tim was
wasting his time with this interview.
Tim paused.
The smile on Andre’s face tightened.
The HR rep gave him a smile that may
have been a smirk.
Finally, Tim spoke up in a small
voice. “I have been at this company for
over six years. I’ve mentored most of
the technical communications team,
including Samantha, who is leaving. I
know the products and services well. I
think I’d make a good manager.”
“And what experience do you have
as a manager?” André asked.
Tim felt on the defensive. The
reality was that he did not have much
managerial experience. He responded:
“I have been mentoring and
supervising the work of most of the
team over the past few years. I’ve also
helped plan and design most of the
implementation side of our technical
documentation suite.”
André nodded. “Yes, that’s
something you’ve done very well,
and which we’re very grateful for and
would like you to continue to do.”
That is all very well, Tim thought,
biting his lip. But why wasn’t that
translating into promotion?
André appraised Tim for a moment,
before continuing.
“We are looking for somebody with
existing managerial experience and skills.
Somebody who can help grow the team
and bring in new skills and ideas. I know
you felt disappointed when Samantha
was given the role of team head, but she
brought invaluable inexperience and
insight from the customer services side
of the organisation.”
Tim nodded. There was nothing he
could really say. André was correct.
André looked down at some papers
in front of him on the table.
“I have been looking at your previous
performance reviews,” André said,
“mostly good, and excellent in some
years. However, last year was just
good. One of the comments about your
performance is that you can be too
abrupt and dismissive.”
Tim went red in the face. They must
be referring to the argument he had
had with Larry, one of the product
managers, who had asked Tim to do
something stupid.“Well, sometimes
straight talking is what’s needed to get
the job done properly.” He stammered.
“That’s fine in your current role,”
André responded, “but if you tried the
same approach with some of our senior
colleagues, that could cause problems.
Sometimes diplomacy is needed.”
Tim nodded and sighed. He
understood. They considered him a
worker bee, not a manager. If they
needed the job done, they’d turn to him.
If they needed someone to manage, they
didn’t think he was suitable.
André thanked Tim for his time, and
told him that his application would be
considered.
Three weeks later a new head of
department was hired. It wasn’t Tim.
Ethical dilemmas
Real-life responses
Readers’ letters in response to Maria’s dilemma,
described in the Summer 2014 issue of Communicator.
However, Tim was asked to mentor
the new head, who came from a sales
background.
Tim felt stuck. He wasn’t really
making any career progress. He seemed
to be in a rut, in the same old position
for a number of years. What should he
do? Should he look for a management
position at another company or
start his own business? Maybe it was
training and experience he lacked.
What about doing an MBA part-time or
getting some management skills under
his belt?
The fact was, when he looked
around, most of those being promoted
into management of technical
publications departments were not
technical communicators: they had
been drafted in from other business
areas, such as marketing, sales and
technology. Perhaps that was one of
the problems: technical communicators
were just not respected enough to be
considered as suitable candidates for
managing large teams.
Or was it just the plain truth that
management was just not for him and
he would be better off and happier in
the long run not trying to fight this,
but just accept his limitations and the
way things were?
Dilemma
Do you agree that Tim is not
management material or that technical
communicators are traditionally not
considered as suitable for management
careers? What do you think Tim could
do to improve his career options? C
Over to you
Write to [email protected]
Tell us how you think Tim should solve his
dilemma. The next issue of Communicator
will feature your responses.
Warren Singer MISTC
Summary of Maria’s dilemma
Kath
Maria had been asked to document
a system that was based on a copy
of the application architecture and
software code from a competitor. She
had been referred to the competitor
documentation for a description of
how the new system worked. Maria
was concerned that this amounted to
plagiarism, but when she had raised
this issue on a number of occasions,
her concerns had been dismissed.
This seems to me to be a problem of
how software development in the
company is being managed. Does Frank,
an in-house developer, have the
necessary experience and expertise to
deliver a top-class system? Perhaps this
is the problem and the organisation
should be looking for expertise external
to the company to deliver a major
project like this. C
Due to the limited space available
extracts from the responses are
provided here.
Roger
This really shows up the lack of
originality and ability of Frank, the
lead developer, and probably of the
whole organisation! The fact that
they cannot come up with an original
application architecture and design,
but are forced to hack the code of a
competitor says it all! Lacking insight
and creativity, they are forced to copy
what others have done.
Mike
Editor’s note:
As technical communicators, we should
be aware that the applications and
systems we are asked to document do
not exist in a vacuum – often borrowing
from best practise and implementations
developed in other organisations.
There is a grey line between trying
to emulate and improve on what
competitors have done and copying
them. On the one hand, as Paul points
out, learning from what competitor’s
have done can make good business
sense. However, doing the same thing
as a competitor may not make good
business sense if it fails to distinguish your
proposition from the competitor’s.
This seems to me to be unethical and
just plain stupid. The loss of reputation
and potential damage would be
enormous if the other company decided
to sue. As for Maria, she’s in a difficult
position. But she certainly should not
plagiarise the existing competitor
guides. She should make an effort to
produce her own guides, in her own
organisation’s style.
As Roger and Kath have pointed out,
plagiarism may be a symptom of a
deeper issue that the organisation should
address. Kath has raised an interesting
point about whether the right resource
has been selected to deliver this project.
In this case, plagiarism may be the
result of lack of expertise and technical
excellence.
Paul
Over to you
Plagiarism is the sincerest form of
flattery. If you can’t beat them, join
them. The sad truth of business is
that most of it is a hack of something
someone else has done previously. If
someone else has designed something
that does it better than you, isn’t it good
business sense to try and emulate that,
rather than wasting years of effort and
time in developing a new system from
scratch, and doing it badly in the end?
If you have a dilemma you’d like advice
about, write to us in confidence. If we
think your issue would be of interest to
a wider audience we’ll air it here (don’t
worry, we will protect your anonymity!).
Note: To protect the identity (and
reputations) of real people, all names
and places are fictitious.
61
62
Adobe tips
The Adobe technical communication Colum(n)
In his regular column, Colum McAndrew offers tips, tricks, explanations and advice on
Adobe technical communication products. In this issue, RoboHelp and FrameMaker tabs.
Adobe FrameMaker users will already
be familiar with the concept of tabs,
but Adobe RoboHelp users will have
only started using them from version
7.
The use of what the software
industry calls a Multiple Document
Interface, adds the ability to have
more than one document or file open
at the same time. This makes it easier
to:
Copy and paste between two files.
Compare content side by side.
Add hyperlinks.
Translate content.
How many is too many tabs?
Whilst multiple tabs do increase your
efficiency, there is a tipping point
beyond which the balance goes the
other way. This is less of an issue in
FrameMaker as you are less likely to
have many files open concurrently.
With RoboHelp this is not the case.
There is no hard and fast method
for calculating the optimum number
of open tabs. You will know when
you hit it though, as you will have to
perform extra mouse movements and
clicks to access content.
Closing tabs
Unfortunately, whilst there are
similarities between FrameMaker and
RoboHelp, closing tabs is not one of
them. What is worse, much of what
follows is undocumented in Adobe’s
product help files!
Closing a single file is easy and
intuitive enough to Windows users.
Both products have an ‘X’ in the top
right corner of each tab. Things start
to get a little trickier when you want
to close multiple files.
RoboHelp tabs also has a right click
menu for closing files. This includes
a useful ‘Close All But This’ option to
leave the currently clicked tab open
(see Figure 1).
FrameMaker users can hold the Shift
key down and use the File > Close All
Open Files menu item. Alternatively,
right clicking on a tab displays a menu
that can be used to close tabs (see
Figure 1).
Working with tabs
There are occasions when you must
have many tabs open. If so, it can
be difficult to move between them,
especially when the tab is not even
visible.
For example, you have ten files
open and you want to copy from file
2 to file 8. File tabs are displayed in
the order in which they were opened.
If the ten topics were opened in
sequential order, there could be quite
a lot of mouse movement and clicking
involved.
Both FrameMaker and RoboHelp
allow you can reorder tabs by clicking
and dragging them into a new
position. You can also use an icon to
display a list of the currently open
tabs from which the required file can
be displayed (see Figure 2). RoboHelp
also has a left / right icon to move the
displayed tabs in the desired direction.
Figure 2: Navigating to open but hidden
RoboHelp and FrameMaker tabs.
can position anywhere you like. The
Consolidate All to Here menu item
brings all FrameMaker windows back
inside the original window.
RoboHelp has a similar concept
which it calls Tab Groups. This allows
you to group topics together and tile
them inside the user interface, with
each tile having its own set of tabs.
For further details on using these,
search for ‘Tab Groups’ on my blog. C
Tabs Groups
Figure 1: RoboHelp and FrameMaker tab
right click menus.
Another look at Figure 1 shows that
there are menu items on offer other
than those previously mentioned. For
example, RoboHelp gives the option to
save the topic and FrameMaker allows
you to open or create a file. However,
what really makes these menus useful
is the other items on there.
FrameMaker has a Move to New
Window menu item. This opens the
tab in a new window. Once open, you
Colum McAndrew FISTC is
an Adobe Community Expert
based in Guildford, UK. His
RoboColum(n) blog is among
Mindtouch’s top 20 influential
technical communication blogs.
W: www.cmcandrew.com
Tw: @robocolumn
Editing
Shall and will: is it worth preserving the distinction?
The difference between these two words and their usage
is discussed by Jean Rollinson.
Definitions
To begin, let’s consider what the
difference is.
From the Concise Oxford English
Dictionary (COED):
‘Shall…1 (in the first person)
expressing the future tense. 2
expressing a strong assertion or
intention. 3 expressing an instruction
or command. 4 used in questions
indicating offers or suggestions.’
‘Will…1 expressing the future tense.
> expressing a strong intention
or assertion about the future. 2
expressing inevitable events. 3
expressing a request. > expressing
desire, consent or willingness. 4
expressing facts about ability or
capacity. 5 expressing habitual
behaviour. 6 expressing probability
or expectation about something in
the present.’
So it seems that ‘will’ has more uses,
but the first two definitions for both
words are much the same.
Usage
However, COED also has a note on
usage, which gives more detail about
the difference.
‘There are traditional rules as to
when to use shall and will. These
state that when forming the future
tense, shall should be used with I and
we…while will should be used with
you, he, she, it and they…However,
when expressing determination or a
command this rule is reversed: will is
used with I and we…and shall is used
with you, he, she, it and they.’
The note goes on to say that as the
contracted versions (she’ll, I’ll etc.)
are more commonly used in speech,
the words are now pretty much
interchangeable.
Bill Bryson also notes in Troublesome
Words that ‘either you understand the
distinctions instinctively or you do
not’. He ends his entry on the subject
by saying ‘In short, it is not possible
to make binding rules to distinguish
between the two and (dare I say it?) no
longer all that important anyway.’
Even Fowler back in 1926
suggested that the distinction was
fast disappearing.
I have also searched all the style
guides that I possess, and none of
them has anything to say on the
distinction, which suggests that it
is not particularly important.
Discussion
So, you might ask, why is the question
still discussed when for many years
the distinction has been considered by
some to be unnecessary and possibly
outdated?
Like many questions of grammar
and usage, the origin is usually down
to those sticklers for language who
feel that the difference is important
in written language, even if it is being
lost in speech. The difference also
still seems to be taught formally
to non-native English speakers
who naturally try to get it right in
their formal writing. Michael Swan
in Practical English Usage devotes
several sections to the use of ‘shall’
and ‘will’ to try to help non-native
English speakers understand the
differences.
One area where usage seems to
contradict the COED’s definitions
is commands or orders. The third
definition for ‘shall’ says ‘expressing
an instruction or command’, while
the third definition for ‘will’ says
‘expressing a request’. Yet ‘will’ is
used for commands and ‘shall’ can
be used for requests (although it may
sound rather formal in speech).
‘Will you be quiet!’ not ‘Shall you
be quiet!’
‘Where shall we go today?’ sounds
more like an invitation to discuss
the options than ‘Where will we
go today?’
Conclusion
To answer my own question, ‘No’
apart from in legal documents, I don’t
think it is worth worrying about which
to use.
Most of the time you won’t be
misunderstood or considered
stupid for using ‘will’ and ‘shall’
interchangeably. There may be
situations where one sounds better
than the other, and native English
speakers will (mostly) instinctively
know which one sounds right. Unless
you are writing or editing legal text,
you are less likely to use ‘shall’, and
using ‘shall’ in everyday conversation
may make others consider you a
pedant or at least old-fashioned, even
if you have used it correctly.
If, however, you want to preserve
the distinction in your own writing,
then that is entirely your choice. But
when editing, I suggest you don’t
impose it on others. C
References
Concise Oxford English Dictionary
11th edition, 2006
A Dictionary of Modern English
Usage H.W. Fowler, 1994
Practical English Usage 3rd edition,
Michael Swan, 2009
Troublesome Words, 3rd edition, Bill
Bryson, 2002
Legal language
The main place where you are likely
to encounter a strict use of shall
meaning a formal instruction or
legal duty is in legal documents. For
example, one of my editing contracts
has ‘The author shall pay the editor’s
reasonable expenses, such as
photocopying, postage and travel.’
This means that the author is obliged
to pay these expenses.
Jean Rollinson FISTCis a
freelance technical author,
editor and proofreader. She is
also an associate of the SfEP.
When not gainfully employed she plays the
clarinet in an amateur wind orchestra.
W: www.authoring-services.co.uk
63
64
Book review
Crystal Clear
David Crystal OBE is a leading authority on the English language.
He’s being interviewed for Communicator by Andrew Peck MISTC.
Andrew Peck: What first spurred your
interest in English and Linguistics?
David Crystal: A curiosity about
languages came first, prompted by my
growing up in a monolingual household
in a bilingual area (North Wales), and
wondering why I could understand
some people and not others. That
led to early second-language learning
(Welsh), and this was supplemented by
other languages in secondary school
and then at university. Moving from
Wales to Liverpool at age 10 led to
second-dialect learning. I didn’t find
out about linguistics until I got to
university, but I devoured books on the
history of English while I was still at
school.
AP: You’ve been writing about the
changes technology is having on our
use of language, whether ‘Netspeak’
or ‘Txtng’. Is this really a new
phenomenon, or have similar changes
happened with earlier innovations? Are
the changes ever a cause for concern?
DC: Every new technology adds a
fresh stylistic dimension to language
structure and use, whether this be
printing, the telephone, the telegraph,
broadcasting... or now, electronically
mediated communication (EMC). Think
of the new varieties of English that
emerged as a result of broadcasting, for
example, such as sports commentary,
chat shows, news reports, and weather
forecasts. EMC is doing the same,
with its many varieties. But it’s too
soon to say whether the linguistic
novelties that have emerged (such as
texting abbreviations) will make any
significant long-term impression on
individual languages. There’s not much
sign of this so far. The amount of new
vocabulary, grammar, and orthography
that has emerged as a result of EMC
is minimal. And there are signs of
the novelty wearing off (much less
textese in young people’s messages
these days). That doesn’t stop the
prophets of doom continuing to predict
linguistic disaster, of course.
AP: We’ve looked back, let’s look
forward. How do you feel English will
change within the next 25 years?
DC: English will continue to increase
its expressive richness, as it always has
done. As EMC becomes increasingly
audio-visual, I anticipate a range
of new, online spoken varieties of
English will develop. And there are
bound to be stylistic changes as a
result of increased reliance on mobile
devices for internet access, with
their smaller screens demanding
more compact expression. But the
main changes will be the continuing
growth of international varieties of
English (the so-called ‘new Englishes’),
as a consequence of English being
a global language, and we will see
a proliferation of new dialects (and
accents) within English-speaking
countries, as a result of immigration.
Technology will also increase the speed
of language change, due to its ability
to circulate linguistic innovation at an
unprecedented rate.
AP: Technical communication is
often about precise use of language
that’s ideally only open to one clear
interpretation. This is a constant
struggle. It sometimes seems that the
more words we use the vaguer we
become! Why is language inclined to be
vague and open to interpretation?
DC: It’s the nature of spoken language
to be imprecise. Face-to-face informal
conversation is the norm, and this
allows all kinds of contextual cues to
aid intelligibility. ‘Look at him over
there!’ Informality doesn’t require
precision: ‘What did you buy?’ ‘Oh,
tomatoes, onions, and stuff...’ Written
language lacks these cues and by its
nature is more formal. But it still has
to cope with polysemy – the fact that
words typically have more than one
meaning. Very few words in everyday
language are monosemic (handkerchief
is one), and as a fair number of these
enter into technical communication the
possibility of ambiguity is always in the
background. Then there are cultural
differences, so that a word which you
thought was safely unambiguous turns
out to have a different meaning in
another culture. Technical language
isn’t exempt, as the case of billion
famously illustrated. But I wouldn’t
exaggerate these problems. Most
technical language in my experience
works pretty well.
AP: Some technical communicators end
up in the profession because they’re
“good at English”, but many of the things
we were taught in school like “don’t use
the same word twice” to demonstrate a
rich and varied vocabulary and “use lots
of adjectives” can be really bad technical
communications practice. Recently
you’ve been critical of the government’s
Spelling, Punctuation and Grammar
tests. Your statement “It’s meaning and
clarity. Clarity unites us.” is something
that most in the ISTC would get behind.
What changes would you make to the
teaching of English to achieve this aim?
DC: I’d want to get grammar seen
as part of a wider context, in which
meaning and effect are central.
Grammar should never be seen as an
end in itself: it’s there to make sense of
words, which by themselves (see above)
are ambiguous. In linguistics, the two
subjects involved are semantics (the
study of meaning) and pragmatics (the
study of the choices we make when we
use language, the intentions behind
those choices, and the effects that the
choices convey). The relevant question
is always: ‘Why?’ Why use one adjective
as opposed to more than one? Why use
passive sentences rather than active
ones? What’s the difference in meaning
or effect on the listener/reader of the
choice you’ve made? I’ve heard some
fascinating discussions in schools when
students are invited to explore the
choices they make.
AP: One of the biggest challenges
we face is communicating about
communication (when preparing style
guides or controlled vocabularies for
example). Do you ever find yourself
meeting yourself coming back when
writing about particularly fine points
of language?
DC: Well, this is my life, isn’t it.
Virtually all my writing is an attempt
to explain how language works in ways
that non-specialist readerships will
understand. I try to avoid problems
by getting someone from the intended
65
readership to read through what I’ve
written before it gets published. For
instance, when I wrote A Little Book of
Language – aimed at young teenagers
– I had it read by a 12-year-old to make
sure I’d got the level right. She was one
of my fiercest critics ever!
AP: Does the grammar of English
vary depending on the genre of
communication? Is there such a thing
as a science fiction grammar, a medical
grammar or a legal grammar? (Is there
really a singular ‘English Grammar’?)
DC: To a limited extent. Stylistic
variations among genres are chiefly
due to other levels of language, such
as vocabulary, layout, and discourse
organisation. But obviously there are
differences of frequency in the use of
particular constructions, and in some
genres certain types of sentence are
conspicuous by their presence or absence
(for example, the use of questions,
commands, exclamations). Work your
way through a major reference grammar,
such as A Comprehensive Grammar of
the English Language, and you’ll find that
only about five percent of the content
is stylistically various. Grammar is the
area of language that is most resistant to
change.
AP: (When) Can we expect to see a David
Crystal book on the linguistic features of
Technical Communication?
DC: I’ve only ever explored this as a part
of a more general study. Scientific and
technical English figured in a chapter of
Investigating English Style, for example,
and of course in the Cambridge
Encyclopedia of the English Language.
And I’ve written the occasional article
on the subject. But a whole book...
Hmm.
AP: You’ve written a lot. What do
you read?
DC: Usually, material relating to the
book I’m currently writing! And I try to
keep up with what’s coming out in the
language field. When I’m off-duty, as
it were, I tend not to read, preferring
to do something more auditory, such
as listening to music or going to the
theatre. But I can’t go into a bookshop
without buying something. My last two
purchases were biographies (David
Lodge, John Carey). I rely on my wife
Hilary, who is a voracious novel reader
(as well as a children’s novelist herself)
to tell me what I mustn’t miss in the
fiction world.
The book reviews
David Crystal has written so many
books, it’s hard to select a few to review.
So I’ve browsed my bookshelf to share
a few of my favourites – some written a
while ago, others more recently.
Spell it out.
Profile Books (2013).
ISBN 9781846685682. If
you’ve ever wondered why
some words are spelt in
what seems a very illogical
way, you should read this book. It
explains that – at the time – there
was some logic behind the decisions.
At least, there was when there were
decisions… sometimes changes in
pronunciation have been part of the
story, and sometimes necessity. Using
just 26 letters to represent a word
based on its sound has led to some
interesting combinations! This book
does give some guides – top tips, if
you like – but the real fascination for
me was in understanding why we spell
‘debt’ with a ‘b’.
Rating: OOOOO
The Stories of English.
Penguin (2005)
ISBN 9780141015934.
This book has been on
the book-shelf for a
few years now, being
the set book for an English Language
course with the Open University. For
those of us who struggle with the
vagaries of US vs British English, not
to mention Australian, South African
and Singapore variants, this book
provides an insight into development
of English both within our own country
and around the world. The rich
dialects that were commonplace only
a few years ago are given page-space
alongside more recent additions to the
language – the technical and scientific
vocabulary we deal with every day.
This book won’t make you a better
technical author – but it will help you
understand why being a good one is
so difficult.
Rating: OOOOO
Rediscover.
Grammar Longman
3rd Edition (2004).
ISBN 9780582848627. This
one is a bit more workrelated. It’s my favourite
grammar book because it explains
both the ‘rules’ (acceptable formal and
informal usage) and the terminology
in language I can understand, with
plenty of examples. If ever I’m asked
to recommend a book on grammar,
this is the one I suggest… and its
complementary cousin, Making Sense
of Grammar.
Rating: OOOOO
Txtng. The gr8 db8.
OUP Oxford (2009).
ISBN 9780199571338. A
balanced account of the
influence of texting on
the language is presented,
using statistics to reassure that the
English language as we know it is
safe in the hands of texters. Another
well-written book that takes an
academic approach to a contemporary
topic in English language usage
while making it accessible to a broad
readership. Given that this book
deals with a technological influence
on communication, it is a must-read
for those of us who find ourselves
documenting the next generation of
devices and interfaces.
Rating: OOOOO
Listen to Your Child.
Penguin (1989)
ISBN 9780140110159. It’s
fascinating watching my
son learn to talk – the way
he puts words together to
make meanings that he understands
even if they sound a little odd to his
parents. This book has shed some light
on the process, explaining that when he
mispronounces a word, he thinks he’s
saying it right – and gets frustrated if
you repeat the incorrect one back to
him. Some of the equipment mentioned
– such as tape recorders – shows the
book’s age, but in general the content
is still relevant – and enjoyable – today.
Rating: OOOOO C
About the author:
David Crystal OBE is a
leading authority on the
English language. His writing
is engaging and prolific; he
has written over 120 books, and numerous
articles and studies into the evolving
language we all share and use.
W: www.davidcrystal.com
B: http://david-crystal.blogspot.co.uk
66
Reflections
Back to school
A group of technicians and engineers from the aviation sector are learning to
access technical communications. Andrew Peck is back in the classroom.
I’ve been granted a short sabbatical
from my workplace (Clearly Stated)
so that I can lecture at De Montfort
University (DMU) in Leicester. The
students I am working with are
technicians and engineers from a
North African navy, who are about to
take delivery of a new helicopter for
search and rescue purposes. Before
they can work on the helicopter,
they need ‘training to type’, which
involves exposure to a mass of
technical communication products
(both manuals and training materials).
I’ve temporarily joined a small and
specialised team of language lecturers
at DMU who’ve been given a few
months to get these men linguistically
up to speed so that they can access
the technical portion of their training
(in common with much of the aviation
industry, the training is in English).
Helping this skilled team limber
up for their encounter is thoughtprovoking. They will be using their
third or fourth language when they
read their new helicopter manuals
and work with the technical trainers,
which is an intellectual challenge
most would balk at. They are
un-fazed and approach their language
education like boxers getting ready
for one more fight… skipping through
pronunciation exercises and pounding
at writing tasks until they reach the
required standard. They are a pleasure
to teach and I’m already confident
that they will reach and exceed the
required standard thanks to the course
at DMU and their own work ethic. I’m
having fun and managing to package
some technical communication
insights alongside the English for the
students that will make them more
effective writers once they get out of
the classroom back to their chosen
careers. As a professional trainer and
teacher, I’m loving the work…but as
a technical communicator I can’t help
but be a bit jealous of the people who
get to work on flying machines.
I’m jealous because normally it’s
me as the author who has to work out
how my audience will think. Before
creating some technical communication
product, I study the people and write
for them. But in the world of flying
machines, the audience isn’t studied,
it’s selected. The helicopter manual is
only used by someone who has reached
a defined standard, which means
that the authors are able to make
assumptions those of us who write for
the ‘generally educated reader’ can only
dream of making. I’m fairly sure that a
certain Swedish furniture manufacturer
has turned its stores into spatially
challenging labyrinths as a warmup
exercise for those who are about to find
themselves facing a bunk-bed futon
hybrid armed with only an Allen key
and a few pictures. Yet still they feature
heavily on the @uselessassist Twitter
feed because they’re missing tricks.
Just because the aviation industry
has a defined audience, it does not
mean those of us working in other
fields can’t benefit from what they do.
Several tricks of the industry can be
applied to any customer group, as they
are just good technical communication
practices that deliver accessible content
to those with different learning and
communication styles. My students
will get face-to-face training as well as
all the manuals: increasingly in-store
demonstrations of products and
techniques are available for many
general products. (The DIY retail
sector deserves special praise in this
respect as many stores have regular
demonstrations in skills ranging from
pointing to plumbing, backed up by
well-written leaflets.)
The students will also be able to
practise in sandbox environments
where they are free to ‘play’ as their
actions will not have consequences.
Pilots get simulators and engineers
get cut away portions of engines
where they can poke around without
damaging things. Financial trading
platforms are very good at educating
their users by providing dummy
accounts where mistakes don’t cost real
money and I feel that more software
companies should take the time to
bundle sandbox data sets with their
software so that customers can play
with impunity.
Finally, and this is important,
they will be taught how to learn and
understand the material before using it
‘in anger’. I’m writing S1000D compliant
documentation on how to re-assemble
the chairs they sit on in class so that
they get used to the format before
they’re faced with the documentation
and product (which means that at some
stage in the next week they’ll have to
put their chairs together as a learning
experience). How many of us assume
that users will intuitively grasp our
conventions before plunging them
headfirst into the task they are hoping
to complete? Users are exposed to so
many conventions and product types
that they can struggle to understand
what you’re trying to achieve with
your content unless you tell them. An
example of someone doing this right
is Peter Grainge who has published
his procedures and style guide on
the web(1). As a fellow technical
communicator I find this valuable,
but I’m also confident that Peter has
taken the time to share this with those
who’ll be using his documentation
alongside the system, and because they
understand how he’s communicating,
they’ll be much better prepared to
understand what he’s communicating.
To conclude, while we can’t all book a
specialist team of university lecturers
to prepare our users for our attempts
at communication, we can all ease them
in gently, present in multiple formats
and give them a safe place to make
mistakes and learn. C
Reference
1.
Grainge P, Advanced Business
Solutions Help Production www.
grainge.org/pages/abs/procedures/
index.htm (accessed August 2014)
Andrew Peck MISTC works for
Clearly Stated as a technical
author. His background is as a
Higher Education lecturer and
military language trainer.
W: www.clearly-stated.co.uk
B: blog.clearly-stated.co.uk
Tw: @writerpeck
One Output
for Every
Screen
Trusted by technical communicators
all over the world to deliver
professional-quality documentation,
Doc-To-Help publishes technical
instructions, policies, procedures, and
training manuals for the web.
Gone are the days when web
publishing only involved the traditional
monitor. Now screen sizes range from
three to 27+ inches and interactivity
has moved from the traditional
keyboard and mouse to touch.
Doc-To-Help has the solution for every
situation: Responsive Help. This new
output responds to screen size and
adjusts itself accordingly. With
Doc-To-Help’s Responsive Help you
need only produce one output for the
web and it will work on any device.
v1
2014
NEW VERSION
SIMPLIFY YOUR TRANSLATION AND MULTILINGUAL PUBLISHING PROCESS
Translation & Localization Services from the Most Trusted Company in Technical Communication
Types of Translation Projects We Handle:
• Technical Documentation
• Employee Handbooks
• Sell Sheets
• Online Help
• Legal Materials (Contracts, Patents, etc.)
• Brochures
• Knowledge Bases
• Medical Translation
• Advertisements
• Operator’s Manuals
• Pharmaceutical Studies & Findings
• Website & SEO Localization
• Quick Reference Guides
• Benefits & Compensation Documentation
• Software Localization
• Safety Posters
• Personal Documents
Our Services Include:
“
Language Translation
Website Localization
E-Learning Localization
Software Localization
Technical Documentation
And Much More!
MadCap and MadTranslations offer first class support and are always available to meet our needs, from assistance with planning the project through to detailed and responsive technical support.”
—Steve Walker | Product Manager, Miro Technologies
COMPANIES WORLDWIDE RELY ON MADTRANSLATIONS
Learn More and Request a Free Quote at MadTranslations.com
[email protected] | +1 (858) 320-0387 opt. 1 | Toll-free US/Canada +1 (888) 623-2271
Copyright © 2014, MadCap Software, Inc., and its licensors. All rights reserved. MadCap Software, the MadCap Software logo, and MadTranslations are trademarks or registered
trademarks of MadCap Software, Inc., in the United States and/or other countries. Other marks are the properties of their respective owners.

Communicator Autumn 2014

Transcription

Similar documents

Minding your language Setting procedures in stone

Power Pick Global Communicator Pro

Cut away, explode or animate?

take an additional 20% off

Adopt-a-thon and Fundraiser Event

xitin - NCSC, National Centre for Science Communicators

element ary school pupils` mag azine

London Bridge station map

October 2015 Newsletter