Communicator Summer 2010.indd

Transcription

Portraying your passions
Job satisfaction needn’t end with your retirement
Communicator
The Institute of Scientific and Technical Communicators
Summer 2010
Facing ethical dilemmas:
tell us what you think
Hearing from users about
MadCap Flare
Reviewing SmartDocs from
ThirtySix Software
Designing and illustrating
content for localisation
3
ISTC news
Communicator The quarterly journal of the ISTC
ISSN 0953-3699
14
Editor
Marian Newell, [email protected]
or +44 (0) 1344 626895
Tony Eyre and Nick Robson
Proofreaders
Decent Typesetting, www.decentgroup.co.uk
26
Advertising
ISTC Office: [email protected] or +44 (0) 20 8253 4506
29
Guidelines
www.istc.org.uk/Publications/communicator.htm
32
Deadlines
copy by
published
copy by
published
copy by
published
copy by
published
Sue Rigby and Elaine Abbott
Enjoying your work right into retirement
Douglas Newton
MadCap Flare goes mobile
Neil Perlin
Exploring key new functionality in version 6
Submissions
Spring
Summer
Autumn
Winter
Creating graphics with localisation in mind
Applying your skills to new subjects
Felicity Davie, [email protected]
or +44 (0) 1344 466600
Subscriptions
Alex Masycheff
Discussing best practices when localising graphics
Tim Joynson, Linda Robins and Jean Rollinson
Layout
Integrating single sourcing into Word
Explaining the capabilities of a product called SmartDocs
22
Copyeditors
Warren Singer
Exploring the reasons for and limitations of such clauses
18
Production team
Disclaimers in technical documents
31 January
21 March
30 April
21 June
31 July
21 September
31 October
21 December
Back issues
www.istc.org.uk/Members_Area/
communicator_archive.htm (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. 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.
Migrating to MadCap Flare
Adrian Morse
Leaving familiar waters for the open seas of Flare
38
Laying the foundations for success
Nicky Bleiel
Saving time and raising quality in single sourcing
42
Structure with FM conversion tables
Andy Lewis
Adding structure to unstructured FrameMaker documents
46
Editing
47
Book review
48
Ethical dilemmas
49
International standards
50
A day in the life
Jean Rollinson
Ed Clayton
Warren Singer
Richard Hodgkinson
Colum McAndrew
cover Douglas Newton with his Bentley Mk VI, the subject of his
cutaway technical illustration (see pages 26–28)
Communicator Summer 2010
4 ISTC news
Out with the old …
In this issue
Marian Newell bows out
As I explained in the Winter 2009 issue,
the time has come for me to hand over
the reins of Communicator to a new pair
of hands. Those belong to Katherine
Judge and she introduces herself on the
facing page. As an experienced technical
communicator and established member
of the ISTC, she is a perfect candidate and
I hope you’ll give her your full support.
As for me, I intend to refocus my efforts
on my first love — writing. If you ever
need a freelance writer, do look me up at
www.newellporter.co.uk.
I’ve had a most rewarding time working
on Communicator. It’s taught me so
much, about people, about publishing
and about technical communication. My
thanks to everyone who has contributed
during my time, especially those
who’ve been there for me on a regular
basis — you know who you are!
Perhaps because I’m retiring from
Communicator, although not from
work, I was pleased to be offered our
cover feature exploring new outlets for
one’s talents in different phases of life.
Members of the ISTC’s online groups
may have seen Douglas Newton’s
questions about marketing prints of
his illustration. Here he explains the
project’s background and execution.
Beyond that, we cover a range of tools
and techniques. It’s a suitably eclectic
mix for an issue that, as well as being
my last, is our new Production Editor’s
first: please give a warm welcome to
James Ducker of Decent Typesetting.
A new interactive series
I want to talk further about one new
item. On page 48, Warren Singer
launches a regular column on ethical
dilemmas in the workplace. This is
something that other associations
have run in their journals and we
hope it will stimulate discussion about
professional conduct. I originally
joined the ISTC’s Council to pursue
ethics-related activities, although more
urgent tasks subsequently intervened,
so I’m delighted to be around for the
start of this series. I hope Warren
and Katherine can count on plenty of
thought-provoking responses.
think of your (new) editor. All editors
are busy people and it is a great help
when contributors do their best to
minimise the work required on their
submissions. Try to:
Make your e-mails clear, concise and
comprehensive
Abide by the contributor guidelines
and house style
Adhere to deadlines for submitting
copy and returning proof corrections
Check your work thoroughly and, if
you can, arrange for others to check
both the content and the writing.
Remember that your peers, potential
employers and prospective clients will
see your article: make it the best
possible reflection of your skills. C
Editorial e-mail addresses
The new address for all enquiries
related to Communicator is
[email protected].
The [email protected]
address will be redirected for a time
but, because of high spam volumes,
will eventually be phased out.
Please update your address books.
Article writing tip #15
It seems opportune to conclude my
series of tips with an exhortation to
Marian Newell FISTC
everything we print is green...
If you are concerned about ensuring your
promotional materials are both costeffective and environmentally friendly, you
should be talking to us.
As an award winning leader in the
field of eco-friendly printing we
cut out the waste and the costs
to give you a great looking
product within your budget
with a sustainable approach.
tel: 01256 880770
web: www.greenhousegraphics.co.uk
greenhouse | graphics |
5
… and in with the new
Katherine Judge steps in
In January 2010, I saw an
advertisement for someone to take on
the role of Commissioning Editor of
Communicator. It sounded ideal for
me, as I can fit the work around my
two young children, so I applied.
It is now a reality and I am taking
over from Marian Newell, editing
Communicator starting with the
Autumn 2010 issue. I am excited
about the task because I will be able
to use and build on my existing
skills and experience in technical
communication.
What have I done before?
My background is in software and I
have over seven years’ experience as a
technical author. I also have experience
of training, editing and project
management. I joined the ISTC in 2002.
How am I preparing for the role?
I have worked for several companies
but with only a few other technical
authors so, having been selected as the
new Commissioning Editor, I decided I
needed to get out and meet some ISTC
members.
I began by attending the first
meeting of the Southern Local Area
Group (Surrey and Hampshire). It was
an informal evening and I met many
friendly faces.
Then, I participated in the Marketing
Frenzy weekend and met even more
people who are passionate about
technical communication and willing to
give up their own time to contribute to
the ISTC.
I have also been doing background
reading by looking at past issues. I now
have over 40 years’ issues on CD. I’m
not sure if I’ll get around to reading
them all, but I’ve read some interesting
articles and I’ve seen how the journal
has progressed over the years.
Next, I will be standing for election to
the ISTC Council in the summer.
What direction should we take?
Communicator is your quarterly
journal and I would like to encourage
all readers, ISTC members or not,
to contribute to it. There is always a
need for articles, letters and feedback.
Communicator would not exist without
contributions from readers and new
ideas are welcome. At this stage, I’d
like to ask:
What articles would you like to see in
Communicator?
What regular features do you like
to read? Are there any new regular
features you would like to see?
Are all areas of technical
communication covered? What would
you like to see more of?
Are you willing to write an article?
I would like to see Communicator
continue to carry high-quality articles
and to maintain its position as a highly
regarded journal. I look forward to
hearing about proposed articles and
receiving your feedback.
What comes next?
To take over from Marian is a tall
order. She has done a wonderful job as
editor of Communicator for the past
nine years and is doing a fantastic job
handing over to me. I still have lots to
learn but I have the support to be able
to grow and develop in the job. I look
forward to receiving your ideas and
submissions for the Autumn 2010
issue onwards. C
Katherine Judge MISTC
www.bedfordtrans.co.uk
We’re talking
your language
Our experienced teams work with technical authors in major
companies worldwide, providing a reliable professional language
service in all disciplines.
19-19a ST ANDREWS ROAD · BEDFORD MK40 2LL · UNITED KINGDOM
TEL: 01234 271555 FAX: 01234 271556
Translation: manuals, patents, documentation
Publishing: your preferred application
Localisation: software & marketing information
Globalisation: your web presence
We comply with the new Translation Products Standard BS EN 15038.
6 ISTC news
Presidential
address
to encourage them to stay with us. The
Marketing and Membership groups are
working together to achieve this.
2. ISTC website
Marketing the ISTC
As you may have read elsewhere, a
‘Marketing Frenzy’ was recently held.
The purpose of this was to come up
with ways of marketing the ISTC to
prospective members and to raise the
awareness of the Institute. We have tried
many ways to do this in the past, with
varying degrees of success, but this is the
first time an event has been organised
solely with marketing as its theme.
Initiatives like this have my backing
and I hope that the ideas and proposals
bear fruit and we can grow the ISTC and
truly make it the ‘Centre for Technical
Communication Excellence’ in the UK.
For some years now, it has been a
concern to Council that membership
numbers seem to follow a trend of
remaining static (at 800–900 members)
for a while, dropping significantly, and
then slowly climbing back to that level.
We never seem able to break this cycle.
I hope this new focus will address
the problem and I will soon be able
to announce a substantial increase in
membership numbers.
Of the ideas that came out of the
Marketing Frenzy, there are two I feel I
need to highlight:
1. Member benefits
The benefits that we, as members of
the ISTC, enjoy include professional
recognition, publications, a sense of
community through channels such as
Local Area Groups, an excellent annual
conference and access to useful resources
such as Oxford Reference Online. These
need to be communicated more effectively,
not only to prospective members as a
selling point but also to existing members
This has existed in the same form since
about 2004, when I was Webmaster. The
content has been continually updated
since to keep it current and accurate,
but the structure has remained fairly
constant. As a result, it began to look
tired and out-of-date. So, we engaged the
services of an external company to help
us with a major redesign and overhaul.
Unfortunately, this took longer than
expected and the launch was delayed
several times. The issues we encountered
have largely been overcome and the new
site is now publicly available. Some areas
are still being worked on, so please
bear with us while we finish these.
Awards 2010: final call for nominations
I am disappointed that my last call for
nominations for the ISTC’s two major
awards did not yield any responses. I
am therefore repeating my invitation.
The Horace Hockley and Mike Austin
awards are important as a means of
rewarding the efforts of individuals in
our profession and our Institute. Please
send your nominations for either or
both, with a brief justification, to the
ISTC Office at [email protected]. All
nominations will be considered and
voted upon by Council members.
As a reminder, the criteria are:
Horace Hockley award
This is an annual award and is presented
to someone who has made a considerable
contribution to the technical publications
industry over a period of time. It is given
in recognition for promoting the industry
across other industries and boundaries,
and for promoting quality in the
industry, whether in training or within
the workplace.
Mike Austin award for outstanding
service to the ISTC
This is a periodic award and is presented
to someone who has made a considerable
contribution to the ISTC over a period of
time. It is given in recognition for
promoting the Institute’s work or for
contributing to its growth and success. C
Simon Butler FISTC
The Institute
The Institute of Scientific and Technical
Communicators is the UK’s leading
body for people engaged in technical
communication. It provides a forum
for members to exchange views and
represents the profession in dealings with
other professional bodies and with the
government. It was formed in 1972 from the
amalgamation of three existing associations.
To join the ISTC or change your grade,
contact the ISTC Office on 020 8253 4506,
at [email protected] or at Airport House,
Purley Way, Croydon, CR0 0XZ.
Council members
President
Simon Butler
[email protected]
Treasurer
Peter Fountain
[email protected]
Website
John Lee
[email protected]
Publications
Marian Newell
[email protected]
Education
Alison Peck
[email protected]
David Farbey
[email protected]
Marketing and events
Paul Ballard
[email protected]
International
Theresa Cameron
[email protected]
Membership
Iain Wright
[email protected]
Linda Robins
[email protected]
Local area groups
Rachel Potts
[email protected]
History and salary survey
Emma Bayne
[email protected]
UK Technical Communication Awards
Galyna Key
[email protected]
InfoPlus+ newsletter
Bob Hewitt (layout and artwork)
[email protected]
Andrew Marlow (content)
[email protected]
7
UK Technical Communication Awards
Does your work deserve recognition?
Are you a student or professional
working in the field of technical
communication? Do you have work
worthy of recognition? Each year the
ISTC grants prestigious awards to
honour clear, concise and effective
information products. The awards
ceremony takes place at the Technical
Communication UK conference
in September, and is an excellent
opportunity to celebrate your
achievements and to catch up on the
latest industry trends.
The deadline for entries is 30 June,
so now is the time to submit your work
and find out how it stacks up against
your peers!
How to enter
To participate, you don’t have to be
an ISTC member. You can submit your
own work, or that of your managers,
colleagues or direct reports.
Entering is very simple, and all the
information is located on the ISTC
website. You will need to fill in two
forms. The first one is to register your
entry, and the second to describe to the
judges the context for the entry to help
them assess how well it achieved its
objectives.
The ISTC accepts entries in five
classes: Descriptive, Instructional,
Promotional, Graphic and Tabular.
When choosing a class, consider which
techniques you have used most and best.
You can save money on your entry
by joining the ISTC. A membership
application form can be found on the
ISTC website.
Call for sponsors
The ISTC welcomes sponsors for
each of the award classes. For more
information, please contact istc@istc.
org.uk.
What to expect
Submitted entries are evaluated by a
panel of judges against several key
elements, including standards and
practices followed in the industry, and
how well the entries meet the purposes
for which they were intended.
You can improve your chances of
winning by carefully describing your
entry. Think in terms of:
Scope
Purpose
Audience
Objectives
Resources (budget, number of people
available)
Constraints (technical, deadlines)
Environment in which the information
will be used (dirty, noisy, rugged)
Any limitations of the delivery
devices (such as a small screen on a
warehouse device)
Past user feedback.
Starting this year, all submitted
entries will receive written feedback
to encourage more transparency.
The feedback will contain valuable
information on what has been done
well, and how entries might be
improved.
You will receive the feedback before
the awards ceremony takes place.
Key features
Classes: Descriptive, Instructional,
Promotional, Graphic and Tabular
Entry deadline: 30 June 2010
Awards ceremony: 22 September 2010
More information: www.istc.org.uk/
About_the_ISTC/
uk_tech_comm_awards.html
Stay in touch
As manager of the 2010 UK Technical
Communication Awards, I look forward
to receiving your entries this year. Let
me know if you need more information
about the awards, and please pass on
your ideas to continue making this
event bigger and better. To find out
more and to submit your work, visit
www.istc.org.uk/About_the_ISTC/
uk_tech_comm_awards.html. C
Galyna Key MA FISTC
Twitter: @sophia_5
You’re in good hands with 3di
Expert documentation and localization services
Technical communication
Supply of technical authors
Information Mapping®
Software products & online help
Technical & compliance documents
Managed outsourced teams
Tools & process strategy
Website & e-learning content
Multi-lingual translation
Information & document design
Project management
Interactive & audio content
Scalable localization testing
www.3di-info.com
3DI Ad 1-3.indd 1
Translation & localization
Email: [email protected]
Tel: +44 (0)1483 211533
13/11/2009 09:27
Communicator Summer
2010
8 ISTC news
Online groups
http://finance.groups.yahoo.com/group/ISTC_Discussion
http://finance.groups.yahoo.com/group/ISTC_IASIG
Who can become corporate members?
A question about who can become a
corporate member of the ISTC became
a discussion about what technical
communication is.
Most members thought that
restricting new members is not good.
ISTC members can include all people
with whom we have something to
share. To increase the number of
members, we must sell the benefits of
the ISTC to people who are interested.
We must not have a restricted
definition of technical communication.
Because a simple definition of technical
communication is not available, some
people who are outside our profession do
not understand what we do.
Some people who do technical
communication work do not call
themselves technical communicators.
A list of job titles that specifies what
technical communicators do is not
practical, because a list cannot include
all the possible job titles that technical
communicators have. The National
Occupational Standards for Technical
Communicators shows the roles of
technical communicators (www.istc.org.
uk/Communication_Resources/National_
Occ_Standards/nos_home.htm).
For one member’s comments about
the discussion, see www.simple-talk.
com/community/blogs/roger/archive/
2010/02/02/89303.aspx.
Benefits of the ISTC
A question about the benefits of
the ISTC to members caused much
discussion. Some frequently mentioned
benefits are as follows:
Membership helps to show a
professional status.
You can put MISTC or FISTC after
your name, which can help you when
you apply for a job. Other members
did not agree, and wrote that
employers value only qualifications
from universities and memberships
of chartered institutes.
Professional contacts can be useful
if you become self-employed, search
for new work, or want to get a
professional opinion.
Communicator, the online groups,
and the conference give you industry
knowledge.
Volunteering has helped one member
to develop her knowledge, skills,
contacts and client base. Some clients
know nothing about the ISTC but they
benefit from her knowledge. When a
client asks about things that she does
not know, she answers, ‘I don’t know,
but I know someone who does.’
An important role for the ISTC is to
show the ‘public face’ of the technical
communication profession.
Plain English and technical communication
A member discussed plain English with
his new manager. To edit documents,
the manager used an organisation
that sells plain-English services. The
manager did not know about the ISTC.
What are the similarities between
plain-English organisations and the
ISTC? Why do people use plain-English
organisations instead of technical
communicators?
In the UK, three commercial
organisations sell an approval service
for plain English:
Plain English Campaign
(www.plainenglish.co.uk)
Plain Language Commission
(www.clearest.co.uk)
The Word Centre
(www.wordcentre.co.uk).
One member wrote that a particular
plain-English organisation is ‘just
another company trying to sell writing
and editing services (as far as I can
tell), but it seems to have positioned
itself as some sort of national guardian
of the language.’
The plain-English organisations have
a simple message: business documents
are more effective if you use wellknown words, short sentences and
correct punctuation.
However, technical communication is
about much more than just words. For
example, technical communication can
include information design and the use
of graphics.
Plain English by itself does not solve
all documentation problems. Long,
unclear documents that have a bad
structure can be written with simple
sentences that use the active voice.
Plain English is not always applicable
in formal documents such as
international standards. Sometimes,
Member news
New members
Member
Peter Burdett
Bristol
Douglas Dennis
Glasgow
Andrew Westfold
Buckinghamshire
Derek Wiggans
Scotland
Sandra Priestley
St Edmunds
Heather Fielding
Cambridge
Stephen Keefe
Kent
Sarah Thomson
Coventry
David Edwardson
Kidlington
Paul Hayward
Bedford
Catherine Leyland
Leicestershire
Ronald Smillie
Aberdeenshire
Genevieve Sherlock Ireland
Steve Moss
New Zealand
Associate
Simon Davis
Exeter
Brian Mahon
Ireland
Student
Judy Selfe
Cambridge
Transfers
Fellow
Kevin Chilton
The Netherlands
Retired Fellow
Anthony Tucker
Wiltshire
changing a word to a ‘simpler’ word
is not correct. In a training course, a
plain-English organisation suggested
changing ‘dwelling house’ to ‘home’.
However, in fire safety legislation, the
term ‘individual dwelling house’ has a
particular meaning. Only experts know
when to use plain English, and when to
keep the technical language.
The ISTC must accept that people
will compare plain English and
technical communication. Therefore,
the ISTC must clearly explain the
difference between technical
communication and the services that
the plain-English organisations offer. C
Mike Unwalla FISTC
Your career. Your future.
on 1
0
fo all % d
rI p
ST ric isco
C es un
m qu t
em ot
be ed
rs
Learn the skills you need to go places
Training funding available
You may be eligible for funding towards your training.
For details of grants that you may be entitled to,
see armada.co.uk/trainingfunding
Technical writing courses
• Introduction to
technical authoring
(1 day, £350) 12 Jul, 23 Aug, 4 Oct
• Intermediate technical
authoring
(2 days, £595) 13-14 Jul, 24-25 Aug,
5-6 Oct
• Advanced technical
authoring
(2 days, £595) 15-16 Jul, 26-27 Aug,
7-8 Oct
Discounted price for above three
courses (5 consecutive days’ training):
£1,195 + VAT.
• Writing for the Web
(1 day, £350) 30 Jun, 3 Sep, 29 Oct
• Basic/Intermediate Framemaker
(2 days, £495) 19-20 Jul, 13-14 Sep,
25-26 Oct
• Advanced Framemaker
(1 day, £350) 21 Jul, 15 Sep, 27 Oct
• Advanced RoboHelp
(1 day, £350) 7 Jul, 22 Sep
Discounted price for both RoboHelp
courses (3 days’ training): £745 + VAT.
(1 day, £245) 7 Jul, 17 Sep
• Acrobat - all levels On-demand
• PageMaker - all levels On-demand
Discounted price for both Framemaker
courses (3 days’ training): £745 + VAT.
• Paint Shop Pro - all levels
E-learning
• Photoshop Lightroom - all levels
• Introduction to Captivate
• QuarkXpress - all levels
(2 days, £495) 8-9 Jul, 16-17 Aug,
30 Sep-1 Oct
• Dreamweaver - website creation
(2 days, £395) 1-2 Jul, 12-13 Aug,
14-15 Oct
• Flash - all levels
On-demand
On-demand
On-demand
• Contribute - all levels
On-demand
• Basic/Intermediate RoboHelp Print and design
(2 days, £495) 5-6 Jul, 20-21 Sep
• Introduction to Illustrator
On-demand
Other courses
Training also available in:
• Journalism, including courses
for editorial assistants and
press ofﬁcers
• Introduction to InDesign
• Business writing, including plain
English, report writing and proposal
writing courses.
• Introduction to Photoshop
• AutoCAD and other Autodesk
applications.
(2 days, £395) 10-11 Jun, 19-20 Aug,
27-28 Sep
(2 days, £395) 19-20 Jul, 14-15 Oct
For more info or to book, go to armada.co.uk or call 01527 834783
www.armada.co.uk
Armada, 6 West Court, Saxon Business Park, Stoke Prior, Bromsgrove, Worcs. B60 4AD
Email: [email protected] Tel: 01527 834783
Scheduled courses take place at our training centre in Bromsgrove in the Midlands, close to the
M5/M6/M40/M42 motorway network. All courses available on-demand at your venue anywhere in the UK.
All prices quoted exclusive of VAT.
armada
10 ISTC news
Financial assistance for students
Introduction
There are many places on the Internet
where you can find information on
getting financial assistance for fulltime, part-time or vocational courses.
Often you must meet strict criteria
to qualify for such funding. Earlier
this year, I wrote a report for the ISTC
in which I discussed the sources I
thought most useful. This short article
summarises my findings. You can
read the full report in the Training &
Education area of the ISTC website.
Overview
Tuition fees for courses vary across all
institutions depending on the subject,
faculty, method and length of study,
as well as many other factors. Typical
annual fees for UK/EU students start
from £2,000 for part-time tuition and
£4,000 for full-time tuition. These rates
are for the 2009/10 academic year, so
check the rates for 2010/11.
As well as paying tuition fees for the
duration of the course, you also have
to consider the cost of supporting
yourself while studying. This is even
more important if you have a family
or other dependants to consider.
Day-to-day living expenses are usually
referred to as ‘maintenance’ costs and
they are not always covered by any
funding you may receive. You need to
investigate any costs associated with
learning, such as buying books and
materials, upfront and include them
when you budget the total cost of
your learning. The maintenance grant
depends on your family or personal
circumstances. Up to £2,906 a year may
be available to students who normally
live in England.
There may be other grants and
bursaries for which you can apply.
‘computing and IT’ categories. In some
cases, you can also follow links to
scholarships in any general subject to
check if you may qualify.
Applying for funding
Funding types
Funding can take the form of loans,
grants, bursaries, sponsorships and
charitable trusts. It can come from:
Government agencies
Try www.direct.gov.uk
Universities
My report discusses:
Coventry University
University of Limerick
University of Portsmouth
Sheffield Hallam University
Other organisations
Commercial course providers
Professional associations
Trade unions
Charities
Sponsors or employers.
Funding arrangements are subject to
change each year, so apply as early as
possible (up to 18 months in advance
for postgraduate courses) and check
the eligibility criteria thoroughly first.
If this news item has been of interest,
do read my full report. While it is by
no means a comprehensive guide to
funding, I hope it will provide enough
signposts to enable you to secure
funding for your chosen course.
Good luck!
Adelaide Nxumalo MISTC
Searching for funding
Various websites enable you to search
for scholarships, bursaries and awards
based on the following criteria:
Level of study (vocational,
undergraduate, postgraduate)
Subject of study
Where you want to study
Where you normally live
Scholarship category.
For technical communication courses,
you may need a little patience to
find a suitable course category. For
example, you may have to search under
‘communication’, ‘language studies’ or
Getting people back to work
During my research, I found an article
called Subsidised Training Programme
for Northern Ireland Graduates Begins.
It reported that Northern Ireland’s
Department for Employment and
Learning has teamed up with two
universities and a business network,
BITC, to offer out-of-work graduates a
solution to unemployment during the
recession. If anyone is involved in such
a scheme or knows of similar schemes
in the UK for graduates as well as
skilled people, please let me know. I’m
sure I’m not alone in welcoming any
positive steps to get people back in
work in the current economic climate.
Useful links
Education UK
Hot Courses Scholarships Search
List of general scholarships available:
www.educationuk.org/pls/hot_bc/bc_edufin.page_pls_user_
scholarship
www.scholarship-search.org.uk/pls/mon/hc_edufin.page_pls_
user_studmoney?x=16180339&y=&a=220707
Funding postgraduate degrees
www.rpi.edu/dept/techcomm/funding.htm
Outline of numerous avenues:
www.postgrad.com/editorial/uk_financial_aid/
Learning and Skills Council
Technical Communication Research Repository
Educational funding in Ireland
www.nidirect.gov.uk/index/education-and-learning/adultlearning/financial-help-1/help-with-learning-costs.htm
The Learning and Skills Council (LSC) exists to make England
better skilled and more competitive, as well as planning and
funding high-quality education and training for everyone in
England other than those in universities.
Educational funding in Scotland
Advice Resources — Funding Directory
http://wales.gov.uk/topics/educationandskills/learners/
worklearning/financialsupport/;jsessionid=chlDKsNYkyhBnlbnJGc
0Tn9pztq5fVtZrhG4bJldpQKNLshNmhlT!58552806?lang=en
Educational funding from over 2000 charitable and non-charitable
organisations
www.adviceresources-fundingdirectory.co.uk/default.aspx
www.careers-scotland.org.uk/Education/Funding/Funding.asp
Educational funding in Wales
All in One.
The Across Language Server is the central platform for all corporate language
resources and translation processes. It helps you to generate multilingual
content at a higher quality, in a shorter time, and for less money.
End to End.
Across enables seamless processes and workflows, from the customer
to the language service provider to individual translators and proofreaders.
The business application features unlimited scalability and open interfaces.
Across.
Hundreds of leading market players including Volkswagen, HypoVereinsbank,
and SMA Solar Technology have already migrated to Across. What about you?
Language Technology
for a Globalized World.
Across Systems UK
Info-Hotline +44 1785 284984
[email protected]
Across Systems, Inc.
Info-Hotline +1 877 922 7677
[email protected]
www.across.net
12 ISTC news
TCeurope Colloquium 2010
Paris in the springtime was buzzing with excitement as technical communicators
gathered en masse for the Content Strategy Forum and the TCeurope Colloquium.
Despite blue skies, bright sunshine and trees in full bloom, delegates crowded
into conference rooms for a very stimulating few days. Terhi Sipilä, President of
TCeurope, shares her views of the TCeurope Colloquium, which ranged from
ancient hieroglyphics to challenges of the future.
The European specialists of technical
communication offered once again a
very interesting view of the profession
at the TCeurope Colloquium in Paris on
17 April 2010. The famous ash cloud
from Iceland prevented one speaker
and some of the participants from
attending but, overall, the colloquium
was a happy success.
Theresa Cameron’s interesting
keynote speech about technical
communication through the ages
worked very well as an introduction and
link to the colloquium’s theme A new
decade for technical communication:
2010 and beyond. She started with
Egyptian ‘Instructions’ from around
2400 BC, continuing with a nice story
Gordon Dennis: Dynamic
communications in air traffic
about Babylonian instructions for
inducing dreams, where the technical
communicator added a part that might
be useful also today: a prayer that the
instructions would work! Two pages of
the instruction manual for the Apollo
13 rocket equipment (‘Houston, we
have a problem’) provided a more
recent example of the value of technical
documentation. The pages were sold
at auction in New York recently for
$45,750.
Another relevant topic was addressed
by Gordon Dennis in his presentation
about dynamic communications in air
traffic, especially from the technical
communications point of view. Safety
criteria are, of course, very strict on
this branch. The presented case gave
concrete examples of the special
requirements for technical communi
cation applications in aviation, and
showed how these requirements were
met and put into practice.
One general group of topics was
language and translation. The audience
certainly appreciated having a speaker
from the European Commission (EC).
Paul Strickland told us about the latest
developments and actions in the EC,
especially the newest initiative, the
‘Clear writing campaign’. Drafting
legislation into all the EU languages
is an unenviable task, especially
when reviewers ‘improve’ the text.
The website for the EC Translation
Directorate has lots of useful
information, including a booklet, How
to write clearly, available at http://
ec.europa.eu/translation/index_en.htm.
The end of the day closed the circle
with Dacia Dressen-Hammouda’s
presentation about the expectations
and challenges of our profession.
Dacia explained us how these are being
met in the technical communications
studies in the Université Blaise Pascal,
in the town of Clermont-Ferrand
in southern France. She ended her
presentation by turning to the audience
to ask for suggestions and opinions
about the future development of the
programme. The audience responded
eagerly with a lively discussion and
useful suggestions.
All the presentations were interesting
Paul Strickland: Clear writing and the
European Commission
but a very important part of the event
was also the comments, questions
and answers of the audience to the
speakers, and the discussions, which
were continued during the breaks.
Time and space is limited here, but why
not come and see the colloquium live
next year in Brussels? The colloquium
was an important experience; the
different views, and the ideas and
feelings they awoke, give a great basis
at least for me to step into the new
decade of technical communication.
The presentations are available
at www.tceurope.org/index.php/
colloquium/25-2010.html.
Terhi Sipilä
Dacia Dressen-Hammouda: Challenges in our profession
13
Technical Communication UK 2010
This annual conference, hosted by
the ISTC, will take place on 21–23
September 2010 at the Oxford Belfry.
Preparations are now well underway.
Following a similar pattern to last
year’s event, TCUK10 offers:
A workshop day
Attend two half-day workshops
Followed by:
Two days of talks and presentations
Attend up to 13 presentations, from
a choice of over 30
Exhibition by vendors and service
providers
Find out what’s on offer and what’s
new in our sector
And:
Plenty of opportunities for discussion
and networking.
Technical Communication UK has a
deliberately broad appeal. The diversity
of the topics covered should reflect the
diversity of what is happening across
the UK. However, a little focus and
depth helps to embed understanding,
particularly on topics that are relatively
new or changing rapidly.
For this reason, we dedicate our third
stream each year to a specialist topic.
It may be something that many of us
are increasingly having to think about
or something that presents significant
opportunities for us to extend our
expertise and influence beyond their
current limits.
This year, focus will be on e-learning.
Here are just three reasons why:
E-learning development can be
seen as the activity where technical
communication and training meet,
and potentially compete. There will
be a gap between our skills and those
we need to develop great e‑learning;
the gap will be different for trainers.
E‑learning can be seen as an
extension of our current portfolios
of deliverables. Whatever kind of
organisation you work for, e‑learning
(whether embedded in a product or
delivered over the web or on disk)
can make a significant difference
to the experience of your users and
customers, and to the costs of your
organisation’s support and training.
It is now so much easier to develop
great e-learning content, and most
importantly, so much easier to
reach a large audience, worldwide.
Increasing bandwidth and increasing
user expectations make it possible,
and a competitive imperative, to
be more creative about how we
communicate with our audiences.
There are, of course, new tools, new
processes and new skills to think
about. There will be things to make
sure we do, and things to make sure we
don’t do. If only there was a technical
communication conference that gave
us the opportunity to investigate and
understand these a little better…
For more information, visit
www.technicalcommunicationuk.com
Rachel Potts MISTC
14 Legal
Disclaimers in technical documents
Warren Singer explores the use and limitations of
disclaimers, exclusion clauses and warning notices.
What is a disclaimer?
Disclaimers, limitation clauses, indemnity
clauses, caveats and waivers are an attempt by
manufacturers of products to limit liability for
financial loss, damage or injury that may occur
as a result of the use of their product or errors
in the product documentation. A disclaimer
attempts to specify or delimit the scope of
rights and obligations that may be exercised
and enforced by parties in a contractual
relationship.
In an ideal world, if the documentation has
been correctly prepared and a user follows
the instructions provided, it should be almost
impossible for the product to cause harm.
For example, if you bought a lawnmower and
followed the instructions, you would expect
the product to be safe to use. However, if you
failed to read the documentation or ignored the
instructions for safe usage, this could result in
damage or personal injury.
One of the premises behind the use
of disclaimers is that if users have been
warned about omissions or limitations in the
documentation, they should be able to take
steps to mitigate or prevent loss or damage. By
proceeding to use the product described in the
document, they have accepted the restrictions
outlined in the disclaimer clauses.
Since the possible legal implications of any
disclaimer are complex, it is advisable to leave
their drafting to professionals with the relevant
legal skills.
Where should disclaimers be included?
Disclaimers should be prominent and visible, so
that users are aware of them, before using the
product.
Disclaimers for user guides are often
included on the back of the first page of a
document, along with any copyright and patent
information. Sometimes disclaimers may be
included on the front page, or any place where
they will be prominent.
In online documentation, disclaimers may
be included in a legal or terms and conditions
section. In other cases it might be appropriate to
include a disclaimer in a specific section or page.
What should they say?
Disclaimers must be suitable for the document
in which they are to be used. They should be
relevant to the user.
Clauses in disclaimers should be clear in
meaning and unambiguous: unclear wording
could lead to problems in enforcement.
Consider carefully how the disclaimer can
be applied and whether the wording could
be misunderstood or interpreted to imply
something else.
Disclaimers should be factual and reflect
legitimate business circumstances. Disclaimers
in standard form contracts intended for
non-business users (consumers) must be written
using plain and easily understandable language
(see reg. 7(1) in the Unfair Terms in Consumer
Contracts Regulations 1999).
Should a business rely on disclaimer clauses?
Not solely. Simply having a disclaimer in a
document does not necessarily mean that the
courts will enforce it in the event of a dispute.
For example, if a customer needs to rely on
the information provided by a business, either
to make a decision or do something (such
as buying, installing, using or configuring a
product), a general disclaimer in a document
may not be enforceable. This is especially true if
it would impose an unreasonable restriction on
the user in the circumstances.
How does the law treat disclaimers?
Firstly, it is important to note that a disclaimer
contained in a user document does not
necessarily become a contractual term, so it is
important that any disclaimers on which you
wish to rely are expressly incorporated into the
contract or end-user licence agreement.
Secondly, when interpreting disclaimer
clauses, the courts will generally apply the
contra proferentem rule, where a clause is
strictly interpreted against the party intending
to rely on it if there is any ambiguity in its
meaning. Therefore extra care should be taken
with the drafting of the wording, to ensure that
it is clear.
Finally, it would be unwise to rely on a single
all-embracing disclaimer clause, because if it
goes too far in one point, it may fail entirely. It
is much safer to separate out the elements into
sub-clauses, so that failure of one part would
not necessarily invalidate the entire clause.
Typically, contracts will contain a clause to the
effect that the striking out by the courts of any
part (as being unenforceable) does not affect
the validity of the remaining parts.
In any dispute between a business and its
customer, the contractual relationship between
the parties is important. However, even where
the parties are not in a contractual relationship,
the law of negligence and statutory provisions
on product liability may apply.
15
Disclaimer examples
information may change without notice, as in most circumstances
it would not be practical to advise users each time a change is
made. See the following example:
Consider the following examples.
Disclaimer for a prototype
The following disclaimer comes from a guide for a prototype
product that is still under development:
The content of this document is furnished for informational
use only, is subject to change without notice, and should not be
construed as a commitment by [Company]. [Company] assumes
no responsibility or liability for any errors or inaccuracies that may
appear in the content of this guide.
[Company] reserves the right to revise this documentation and to
make changes in content from time to time without obligation on the
part of [Company] to provide notification of such revision or change.
The next example illustrates that disclaimers can be quite
specific and detailed in their wording (which is often required to
avoid ambiguity in their interpretation).
This publication could include technical or other inaccuracies or
typographical errors. Changes are periodically added to the information
herein; these changes will be incorporated in new editions of the
publication. [Company] may make improvements and/or changes in
the services or facilities described in this publication at any time.
This disclaimer would not be appropriate for a document
that users will need to rely on for more than informational use.
Think of the example of the lawnmower user guide: how much
confidence would you have in the manual (and product) if you
read the above disclaimer?
Disclaimer regarding warranty
Website disclaimer
User guides for products may include disclaimers of warranty, as
illustrated in this example.
The following disclaimer comes from a company website:
The material and information contained on this website are for
general information purposes only. You should not rely upon the
material or information on the website as a basis for making any
business, legal or any other decisions. Whilst we endeavour to
keep the information up to date and correct, [Company] makes no
representations or warranties of any kind, express or implied about
the completeness, accuracy, reliability, suitability or availability with
respect to the website or the information, products, services or related
graphics contained on the website for any purpose. Any reliance you
place on such material is therefore strictly at your own risk.
[Company] provides this documentation without warranty, term,
or condition of any kind, either implied or expressed, including,
but not limited to, the implied warranties, terms or conditions of
merchantability, satisfactory quality, and fitness for a particular purpose.
[Company], its employees and agents will not be responsible for any
loss, however arising, from the use of, or reliance on this information.
However, consider whether this disclaimer might be overridden
by other warranty terms (express or implicit) in the sale of the
product.
Clause indicating legal jurisdiction
It is typical for websites to include a caveat that usage is at the
user’s own risk. This sort of disclaimer is often seen on websites
where there is no contractual relationship with users. However,
for websites that sell products or services directly, a visitor may
indeed need to rely on the information to make a decision. In a
liability case, this clause might not be enforceable.
The disclaimer section in a contract should contain a clause that
indicates the relevant legal jurisdiction that applies (in the case of
disputes with customers). For example:
Disclaimer for a support site
The ‘home’ jurisdiction — where the company issuing the
disclaimer is situated — is usually (although not always) selected.
If no jurisdiction is specified, this could result in conflicting laws
from different countries being applied, which could have a
significant impact on whether the disclaimer is enforceable.
Although documentation is often prepared with the best
of intentions, information may sometimes be out of date or
inaccurate, in which case a disclaimer would be appropriate. See
the following example from a support site:
Whilst [Company] makes every attempt to ensure the accuracy
and reliability of the information contained in the documents stored,
served and accessed on this site, this information should not be relied
upon as a substitute for formal advice from [Company].
This disclaimer will be governed by and construed in accordance
with English law, and any disputes relating to this disclaimer will be
subject to the [non-]exclusive jurisdiction of the courts of England
and Wales.
Disclaimers to prevent libel
A document that contains examples and names might contain a
clause along the following lines:
This disclaimer has the unintended implication that users
should call technical support to resolve issues, which may not be
what the company wants or what users expect. This demonstrates
that attention to wording is essential when preparing disclaimers.
The example companies, organisations, products, names, e-mail
addresses, people, places, and events depicted herein are fictitious. No
association with any real company, organization, product, name, email
address, person, places, or events is intended or should be inferred.
Disclaimer clause about changes
Of course, you should be using fictional information in your
examples, and not just seek to absolve yourself of responsibility
by stating this in the disclaimer.
It would be advisable to include a disclaimer in a user guide that
Whether the contract is between businesses
or between a business and a consumer affects
the legal outcome if the disclaimer is to be
enforced in UK courts. Consumers are afforded
greater protection (via the statutory provisions
mentioned below) but business-to-business
transactions are essentially unregulated and are
subject to the general common law of contract.
When a user accepts the terms and conditions
of a contract, these are generally binding unless
it can be proved that:
The relationship between the parties was
unequal, and
The conditions are particularly onerous and
unfair on one of the parties, or
There are other express or implied terms
16 Legal
IMPACT
LOW
HIGH
LOW
HIGH
PROBABILITY
Disclaimers will not protect your business if the
documentation that a user needs to rely on is
faulty, missing key information or misleading.
One of the best ways to prevent injury to
users and protect your business from liability is
to ensure that you have the appropriate quality
control procedures in place and that the manual
is written by someone qualified to write it and
reviewed thoroughly for errors by the company
prior to release.
As a final line of protection, the business should
ensure that appropriate insurance is in place.
What about the release of a draft version?
Figure 1. Risk matrix
Probability: how likely are there to be errors in the document?
Impact: what would be the significance of the error on the customer?
that contradict or overrule the disclaimer
clauses (some of these terms may be implied
by statute, such as the UK Sale of Goods Act
1979, the Supply of Goods and Services Act
1982 and the Unfair Contract Terms Act 1977).
In particular, a clause purporting to exclude
liability for death or personal injury caused by
negligence is rendered void by section 2(1) of
the Unfair Contract Terms Act 1977.
Consumer contracts in the UK are subject
to the Unfair Terms in Consumer Contracts
Regulations 1999, which are intended to
ensure that businesses cannot rely on unfair
disclaimers or exclusion clauses to protect
themselves from liability to users. A disclaimer
could be considered unfair if it attempts to
absolve a business of its legal responsibilities
towards its customers.
You should consider these points before
releasing any documentation to customers.
What can customers do about faulty documentation?
To understand the impact of disclaimer clauses and their ability to prevent
liability for faulty documentation, it helps to understand the legal remedies
available to a customer to redress any grievances. These depend on the
nature of the grievance and on the relationship between the business and its
customer. Here are some examples of what customers might do if the product
documentation were faulty:
Request the return of their money
Ask for compensation for lost revenue or business
Where injury or serious damage results from use, sue for negligence.
Consider the following examples:
Case 1: A customer is frustrated by the general poor quality of an
installation guide, which doesn’t fully explain how to use the product. He
contacts the company and requests his money back.
Case 2: The sales documentation on the website promises a number of key
product features and, on the basis of this, a client purchases the product and
integrates it into other systems. However, some of the key features promised
are either unavailable or do not work as advertised. The client complains that
they were mis-sold the product and suffered financial loss as a result.
Case 3: A consumer using a heating appliance suffers severe scalding and
there is fire damage to a living room. The documentation failed to warn
adequately about safe usage of the product.
Would disclaimers and exclusion clauses be effective in these cases? The short
answer is probably not.
Sometimes information that has not been fully
reviewed needs to be sent to a customer to meet
a product deadline or agreed delivery date.
Consider carefully the circumstances in which
you are prepared to release draft versions:
How significant are the updates?
How confident are you in the information
currently supplied?
Have you conducted a risk assessment of the
likely impact of an error in the documentation
on the client’s business?
Figure 1 shows a risk matrix.
If the risk of an error is high and this is likely
to have a significant impact on the customer
(the dark red area in Figure 1), the document
should not be released.
If the information in a document is inaccurate
and unreliable, should it be released to
customers? When releasing draft documents to
customers, you should include disclaimers that:
Make it clear that this is a draft
Clarify the circumstances under which the
draft can be relied on and the manner in
which it should be used
Indicate any sections that are inaccurate or
that the customer should not rely on.
What are the implications for suppliers of technical
documentation?
A common question asked by technical
communication contractors and suppliers is
whether they may be held liable for any faults
in the technical documentation they supply to
clients.
Firstly, it is important to note that the
relationship between a technical communicator
and a client is a business relationship, not a
consumer relationship.
From a legal perspective, their clients’
businesses would always be directly answerable
to their own customers for any legal actions.
It is unlikely that the businesses would
seek redress from suppliers of technical
documentation unless it can be proved that
the suppliers acted in a negligent manner in
producing the documentation.
Sole authors often do not have control
over the contractual arrangements between
themselves and their clients. In most
17
circumstances, the contract is given to
them on a take-it-or-leave-it basis. In these
circumstances, they should:
Keep a record of e‑mail reviews and
reviewed copies to ensure that they can
demonstrate that they followed due
process in drafting and reviewing the
documentation
Request formal sign-offs from authorised
business representatives before releasing
documentation
Consider indemnity insurance to protect their
businesses.
Remember, contractually, if the relationship
between supplier and client is not on an equal
footing (for example, the client dictated the
contract terms and conditions), the client may
not be able to hold the supplier accountable for
particularly onerous clauses.
Use of warning notices
Warning notices and caveats function like
disclaimers in some ways. The objective of
including them is to mitigate against the risk of
damage or harm to users by pointing out:
Defects or flaws in the product that may
cause harm
Restrictions or limitations on the use of a
product
Important notifications for safe usage of the
product
Types of use for which the manufacturer
accepts no liability.
Warning notices are the result of due process
in testing and quality control of the product
before it is released to the customer. Testing
should cover all likely scenarios in which the
product will be used.
In order for warnings to be effective, they must
be prominent and visible, and used only to warn.
Notes and tips should use a different style.
Conclusion
Disclaimers and similar devices are useful
features in documents for limiting the risk of
liability. However, their usage should comply
with some basic principles. They must be:
Prominent and visible
Drawn to the customer’s attention before use
of the product (or risk not being effective in
law)
Appropriate for the document and relevant to
the user
Factual and descriptive
Clear and easy to understand
Free of onerous or unreasonable conditions
on users
State the legal jurisdiction that applies to
their interpretation
The inclusion of a disclaimer may not
necessarily protect your business from liability.
It is best to ensure that the product and
documentation have gone through rigorous
quality control, that instructions are provided to
ensure safe assembly and usage of the product
and that adequate insurance is in place. C
Warren Singer MISTC
is a founding partner
of Cambridge Technical
Communicators, a
consultancy business,
based in Cambridge,
UK. He has 15 years’
international experience
as a technical
communicator.
W: www.technicalcommunicators.com
Acknowledgements
The author would like
to thank Sean Redmond
for his insightful
contributions to this
article.
Ovidius – Systematic Success
TCToolbox –
The trusted solution
for technical content
management
TCToolbox
Webdemonstration
www.ovidius.com
Book your live
demonstration
by emailing
[email protected]
18 Product review
Integrating single sourcing into Word
Alex Masycheff explains how a product called SmartDocs integrates
many single-sourcing capabilities into Microsoft Word.
If you ask a technical writer to name the five
most popular single-sourcing tools, there’s
a good chance that the list will include
FrameMaker, RoboHelp, Flare, Doc-To-Help
and probably some XML-based tools. I can bet
Microsoft Word will not even be mentioned.
There’s a good reason for this: implementing
techniques such as content conditionalising,
content reuse and multi-channel publishing in
the way that we can in single-sourcing tools is
virtually impossible in Word.
This results in a serious dilemma. On one
hand, many technical communicators need
to single source their documentation. On
the other, they are often tied to Word for
historical or budgetary reasons and have to
use inefficient methods (such as copy-andpaste) that increase the cost of creating and
maintaining content. This is where a product
called SmartDocs can come into its own. It’s
an off-the-shelf product that lets you integrate
many single-sourcing capabilities, including
reuse and conditionalising of content, into the
Word environment. SmartDocs is developed
by ThirtySix Software (www.thirtysix.net), a
US-based company that specialises in building
content management solutions on the Microsoft
platform.
We began to use SmartDocs intensively for the
first time when our company was developing a
solution for a client that had:
Over 20 products, each with several flavours
A tremendous amount of reusable and
constantly updated content
Content variations for each product
depending on individual customer’s
requirements
Several technical writers in a team.
SmartDocs was a great help because it enabled
us to address most of the client’s needs and
reduce the cost of creating and maintaining the
documentation.
Introducing single sourcing to Word
SmartDocs operates with chunks of information
called snippets. A snippet is a portion of content
that can be used in multiple places. Snippets are
stored in the SmartDocs repository on a server.
When you create a new document, you query
the repository and pick up the snippets you
need for the document. Because you can assign
metadata (for example, content category,
product name or release) to each snippet,
snippets can easily be found in the repository.
Of course, a document can contain regular
content that is not stored as snippets.
A snippet may include conditional content
and variables. You can expose or hide certain
conditions and define variable values depending
on your requirements for the content to be
included into the final deliverable.
When you update a snippet, SmartDocs can
propagate the change to all the documents in
which the snippet appears. Alternatively, you
can choose to stay with an older version of the
snippet in a specific document.
However, while SmartDocs provides
excellent capabilities for content reuse and
conditionalising, it does not enable multiple
formats to be generated from a single source.
If you need output formats other than Word,
PDF or simple HTML, you will need a separate
publishing tool to generate them.
SmartDocs components
SmartDocs consists of two components:
Repository of reusable content, in which
snippets are stored. The repository is stored
on a server and the underlying infrastructure
is Microsoft SharePoint. You can use Microsoft
Office SharePoint Server (MOSS), if your
organisation is already using it, or you can
use Microsoft Windows SharePoint Services
(WSS), which is a free add-on for Windows
Server 2003 and 2008 that you can download
from Microsoft’s website. If you do not want
to host the repository on your own servers, it
can be hosted on ThirtySix Software’s servers.
SmartDocs Client, a Word add-on installed
on local computers. This enables you to
access the repository from Word, to insert
and manage snippets in documents, and to
conditionalise content.
Configuring the repository
Configuring the repository requires some
understanding of SharePoint, but you can
quickly gain this knowledge by reading the
SharePoint and SmartDocs documentation.
The configuration process is pretty well
documented: it took us about 30 minutes to get
the repository up and running.
As a minimum, configuration involves setting
up several components:
Snippets metadata, which you need for
categorising and locating snippets. For
example, if you created metadata such as
Category, Product Name and Product Release,
you will be able to run search queries such as
‘Find all snippets that relate to the Installation
of the Release 5.0 of Product ABC’ and use
that content in your other documents.
19
Snippet folder structure, which you can use
to categorise your snippets further in the
repository.
Access permissions, which you need to assign
different privileges to the members of a
documentation team. For example, you may
want to give a documentation manager the
right to create, update and remove snippets,
while other writers are restricted to using
existing snippets.
Installing the SmartDocs Client
Installing the SmartDocs Client is just a matter
of clicking the Next button in the Setup Wizard
and defining some optional settings, such as
the location of the SmartDocs client on a local
computer.
There is a single installation file for Word
2003 and Word 2007. If you have both versions
installed on your computer, the installation
program will ask you for which version you
want to install the SmartDocs Client.
The SmartDocs Client is required for only
those users who will work with the SmartDocs
repository (for example, creating, updating
and removing snippets) and conditional
content. Reviewers who only want to read Word
documents do not need to install the SmartDocs
Client; they can work with snippets in the same
way as regular content.
Figure 1. Word with the SmartDocs Task Pane
Creating a snippet
A snippet can contain any content. To add
a new snippet to the repository, you just
select the portion of content, click Create
new reusable snippet and enter data about
the snippet in the wizard (Figure 2). The
information you are prompted to enter is based
on the metadata configuration that you defined
when setting up the repository.
After the snippet is stored in the repository,
you can reuse it in multiple documents.
Working with SmartDocs
After the SmartDocs Client is installed on your
computer, you will see a new SmartDocs tab
in the Office 2007 ribbon (or new menu in
the Word 2003 menubar). You can use this to
perform various operations, including creating
new snippets, searching the repository, and
managing conditional content. Alternatively,
you can use the SmartDocs task pane to
accomplish these tasks (Figure 1).
Inserting a snippet
When you assemble a new document in which
you want to use a snippet from the repository,
there are several ways to locate the snippet:
You can define a search query using the
snippet metadata defined when configuring
the repository. Figure 3 shows an example of
such a query.
Figure 2. Create Snippet Wizard
Figure 3. Querying the repository
20 Product review
have it change in all the places where it occurs
can save hours of work.
When you update a snippet and then open
one of the documents in which it is reused,
SmartDocs notifies you of the change by
displaying a message in the bottom right corner
of the screen (Figure 4). Clicking the message
lists the updated snippets in the document
(Figure 5).
You can compare the updated version of
the snippet with an earlier version and decide
whether you want to propagate the change into
the current document or retain the previous
version of the snippet.
Working with conditional content
Figure 4. Update Notification
Figure 5. Update Snippet dialog box
You can use the folder structure of the
repository to help narrow your search.
You can search for a snippet by name.
Matching snippets are displayed on the
SmartDocs task pane. From there, you can
double-click or drag-and-drop the desired
snippets into your document.
After a snippet is inserted, it is highlighted
by a blue frame. If you position the cursor
anywhere inside the snippet, the task pane
displays the snippet’s metadata.
Unfortunately, the current version of
SmartDocs does not enable you to view a report
of all the documents in which a particular
snippet is reused. This is an important
capability because technical communicators
usually want to understand the impact of
changing content that is reused in multiple
places.
Updating a snippet
This is one of SmartDocs’ strongest features.
The ability to update content in one place and
Working with conditional content in SmartDocs
is similar to working with single-sourcing tools
such as FrameMaker or RoboHelp. You start
by creating conditional views (an analogue of
conditional tags in FrameMaker) by defining
their names and colour. Then you can select
a portion of content and apply a conditional
view. (Of course, you may apply more than one
conditional view to the same content.)
To filter conditional content, you select which
conditional views you want to expose and hide
(Figure 6).
One feature that I miss is the ability to store
conditional views in the repository. This would
enable documentation teams to maintain
consistency across the work of different
technical communicators and avoid duplication
of effort through the creation of conditional
views with the same purpose but different
names.
Working with variables
SmartDocs differentiates between global and
local variables.
Global variables are stored in the repository
and can be used in multiple documents. You can
define a value of a global variable either in the
repository (whenever you change the variable
value in the repository, the change will occur in
all documents in which the variable appears) or
in each document (you use consistent variable
names in multiple documents but define their
values for individual documents). SmartDocs
lets you lock a variable value so that writers
cannot make arbitrary changes to its value;
this is especially useful for legal and copyright
information.
Local variables and their values are declared
in individual documents and are not shared
across documents.
Using snapshots
Snapshots is a feature that I especially
like in SmartDocs. Imagine this: you have
several conditional views and variables.
When you prepare a document for delivery
to a specific customer, you need to use a
21
certain combination of exposed and hidden
conditional views, and also to define variable
values.
Instead of doing this every time you
prepare a delivery, you save a combination
of exposed and hidden conditional views
and variable values and then just invoke this
saved configuration in one click. This is what
snapshots are all about.
Figure 7 shows existing snapshots that
represent different deliverables. When you
double-click a snapshot on the task pane, the
document updates accordingly.
Summary
SmartDocs is a powerful tool that finally
integrates the world of single sourcing into
the traditional environment of Word. With
SmartDocs, not only can you reuse and
conditionalise content without moving to a
new tool, you can also use the capabilities
of SharePoint to enhance your document
management and content management
abilities. If you have a fair amount of reusable
content that needs to be effectively updated
and managed, SmartDocs can save you many
hours of work and bring you a payoff very
quickly. Your customers can now receive
customised and up-to-date documentation that
you can easily maintain.
On the negative side, if you publish your
content to multiple formats, such as online
help or HTML help, you will still need an
additional tool to convert Word documents to
other formats; this may mean that SmartDocs
is not the tool for you. Otherwise, SmartDocs
provides an effective way to single source
documentation in Word. C
Figure 6. Conditional Views
Figure 7. Snapshots
Alex Masycheff is a content management consultant
at WritePoint, a technical documentation company
based in Israel. Alex develops and implements
solutions that help documentation teams
effectively create, customise, and publish technical
documentation. He also advises organisations
on choosing the right techniques, technologies
and tools, and teaches companies to use content
management concepts in practice.
W: www.writepoint.com
22 Translation
Creating graphics with localisation in mind
Sue Rigby and Elaine Abbott, DTP specialists at Lloyd International
Translations, discuss some practices for localising graphics.
With the rapid growth of the Internet, most
companies can have customers from all over the
world looking at their website and potentially
buying their products. Graphics and images
form a crucial part of almost all communication
materials. Clever use of images can help you
communicate more effectively with your
existing and future customers, while the use
of graphics and images can improve the whole
localisation process.
Humans recognise images more easily than
text. Studies suggest that first we analyse the
general structure and shape of an object, then
the detail. Text and image excite different parts
of the brain: a good image aids the memory to
visualise. It is easier to depict a complex process
or technical procedure using a flowchart or
detailed graphic. Good authors will include
graphics in their communication materials and
these graphics will need to be localised.
In this article, we will address some of the
challenges of localising graphics and how you
can optimise your source files for localisation.
Translating the text in a document is just one
aspect of localisation. Localisation considers the
whole process of adapting the original content,
both linguistically and culturally, to the new
target audience — considering not just the text
but factors such as style, use of images, colour,
graphics and technical jargon. For example, in
the UK, the date format is dd/mm/yy and in the
United States it is mm/dd/yy.
Graphic preparation
Technical manuals and documents contain
many complex graphics and those graphics may
require the insertion of text to complete the
illustration. One of the basic rules for successful
localisation is to consider localisation at the
planning stage: create documents and graphics
with localisation in mind. This very much applies
to the development of graphics. Graphics, such
as flowcharts and diagrams, might have been
obtained from a variety of sources within an
organisation, or from previous documents. Over
time, it is quite common for the original source
files to be untraceable: graphic files may have
been converted to .jpg or .eps format and simply
inserted into the document. A common error is
not being able to trace back to where the original
graphic came from. This causes problems in
the localisation process because the graphic
cannot be edited. When it comes to localising
your publication, software or website, provision
of the original graphics is very important for a
smooth and cost-effective process.
Providing access to text layers in the original
graphic file format will increase cost savings
and reduce the time required. For example, in
order to localise a .gif or .jpg file, the original
Photoshop (.psd) or Adobe Illustrator source
file is needed along with overall style guides
that were used to create the original graphic:
colour information, preferred fonts, design
specifications and export or save settings.
If the original graphic is not available and
you have to supply a non-editable file, then
your localisation provider can create a new text
box; overlay it onto the original graphic thereby
covering the original text. This is possible if
the original text is on a white background but
not if the background is coloured, as shown in
Figure 1.
Graphics create challenges to the localisation
process, often generating additional costs
and increasing project time. Problems arising
from graphics in a source language file will be
multiplied by the number of languages into
which the project is to be translated. It is in
everyone’s interest to ensure that the graphics
and images are optimised before the localisation
process begins. Localisation Service Providers
like Lloyd International Translations (LIT) are
able to carry out much of the optimisation but
this simply adds to the cost. Clients can play
a vital role in making the process as smooth
as possible. A basic understanding of graphic
preparation can help reduce costs significantly
and improve the quality of the overall
localisation project.
Text expansion
When you translate from English into another
language, the translated text will take up more
space. Most languages are longer than English
by about 15%; languages such as Russian can be
up to 40% longer. Once the text in the graphic is
translated, text expansion can cause problems
��
��
��
��
��
Range per
1.000mm
��
Figure 1. New text cannot easily cover the original
text on a coloured background
23
HOME SCREEN
Serial Company
Language
number address
page 63
SERVICE
System
Diagnostics Adjustment
Config.
PRINT SETTINGS
Machine Print height/
settings
width
page 66
page 66
Print
orientation
page 67
PRINT HEIGHT/WIDTH
page 63
Default Print
Height
Default
Print Width
page 66
Figure 2. Text in a graphic originated in English
PARAMETRES D’IMPRESSION
L’ÉCRAN PRINCIPAL
RéglagesLargeur/HauteurL’orientation
d’impression d'impression d’impression
Numéro Addresse
Language
de série de votre
page 66
page 66
page 67
société
page 63
LARGEUR/HAUTEUR D’IMPRESSION
SERVICE
Hauteur
Largeur
Config
d'impression
d'impression
Diagnostics Adjustment
Système
par défaut
par défaut
page 66
page 63
Figure 3. Text in the graphic after translation into French
with the original layout of the graphic. In
Figure 2, we can see an example of a flowchart
graphic containing some simple English words.
To illustrate the problem of text expansion, in
Figure 3 the text has been translated into French
and no longer fits the boxes, causing problems
with the original layout of the flowchart. Text
expansion does not always occur as a result
of other languages taking up more space;
sometimes it arises because they avoid the use
of abbreviations and hyphenation, which also
alters the layout of the translated text.
In Figure 4 we can see a simple engineering
diagram, containing text. Once translated,
the text in this graphic could overlap other
elements of the graphic. This could result in a
DTP (Desktop Publishing) specialist having to
reposition the text lines manually.
A simple way of minimising issues caused
by text expansion is shown in Figure 5. The
same graphic has been created using numbered
callouts or captions corresponding to the text in
an adjacent table. The numbered callouts could
also be simply referenced in the main body
of text. This is a much more effective way of
creating a graphic with text. Here, localisation has
been considered from the start. In Figure 5, there
is enough room in the table to take into account
any text expansion. In the event of the translation
being exceptionally long, the translated text will
‘wrap’ to a second line in the table cell.
Use of CAT tools
Localisation of graphics typically involves
replacing the source text with the translated
target text. This is usually carried out with the
use of computer assisted translation (CAT)
tools, such as SDL Trados. Software enables
localisation service providers, like LIT, to
extract the text from graphics created in some
packages, such as Illustrator or CorelDraw, into
.rtf format.
In order to minimise costs, try to avoid any
text in graphics in the first place and create the
text in the document itself. This requires less
work as the graphic text is part of the main
document and not a separate entity inside
the graphic file. This ensures that the text
will appear ‘in sequence’ to the translator and
allows the text to be incorporated more easily
into Translation Memory. If the text must be
adjacent to graphic elements, try to position
it in such a way that there is some horizontal
space for text expansion; ensure that the text
is in a text box and that no hard returns are
contained within the paragraph. When the
Translation Memory tools analyse segments,
the text is usually segmented at a logical break,
such as a hard return. Inserting a hard return
into a paragraph (for example, to fit a long
sentence into a narrow text box) can negate the
benefits of using CAT tools, or simply mean
your localisation provider takes longer at the
24 Translation
Did you know?
Swedish furniture
giant IKEA has
159 stores in 29
countries. Their
website is available
in 39 languages.
They favour the use
of graphics in most
of their product
communications:
IKEA tends to use
word-free diagrams
in the furniture
assembly manuals:
80% of instructions
are word free
images and only
20% require text to
communicate safety
features.
Flowcell Wall
Figure 4. Text as part of a graphic
�
�
�
�
Temperature Transmitter
RTD
Coupling
Flowcell Wall
Figure 5. Text applied using callouts
file preparation stage, deleting the hard returns
ready for the Translation Memory analysis.
Help your localisation provider
There are many ways you can improve the quality
of your localisation projects and keep costs down.
Take a strategic view of all your localisation
activities and establish a long-term relationship
with your chosen localisation provider. In time,
you will benefit from the cost savings made
using Translation Memory technology and a good
provider will build terminology glossaries to
suit you and your industry — including text from
diagrams and graphics. Your team of translators
will become familiar with your products and
standard documents and manuals that you
produce. The consistency of using the same team
will mean you can build a library of graphics that
can be quickly and efficiently localised — graphics
that have been optimised for localisation.
Provide a list of graphics
When supplying source files to your provider,
good practice is to provide a document listing
all the graphics, along with their respective
formats and information relating to each
graphic: For example, which graphics do not
have translatable text, graphics that do include
text and where the respective pages and files
can be located.
Import ‘from file’
Import graphics ‘from file’ into your original
source documents. This creates a referenced
graphic, so that your document contains a
link, not the entire graphic file. Use a relative
pathname to the source graphic. In other
words, have a logically placed subdirectory
where all document graphics are present.
Your localisation provider should mirror your
directory structure to ensure that documents
open properly with imported graphics at both
the supplier and client locations.
Localising screenshots
Localisation of graphics does not just affect
technical manuals and marketing materials.
Online Help and documentation can contain
graphic elements that pictorially display
the User Interface of localised software. The
localised software must be made available so
that new screenshots can be taken.
The localisation of software is a completely
separate topic that we do not have time to
discuss now. For the purpose of this article,
the key consideration for localising graphics
in software applications is to ensure you use
the final version of the localised software to
recreate your graphics and recapture your
screenshots.
Keep graphics culturally generic
As well as technical considerations, when
localising graphics, you must take into
consideration the culture or religion of the
country. Each culture has different value systems;
varying beliefs and interpretations of non-verbal
communication. For example, in China the colour
red and the number eight are considered lucky.
In Japan, black and the numbers four and nine
are considered unlucky. Considering localisation
from the outset is the key to success.
25
Golden rules for successful graphics localisation
Create graphics with localisation in mind.
Considering localisation when you create your
source files will help avoid problems further
down the line and ultimately reduce the cost
of the overall localisation project.
Help your localisation partner by providing
editable graphics in the format in which they
were originally created. For example, a .jpeg
or a .gif will have been originally created in
another package such as Adobe Photoshop.
Try to avoid embedding text in graphics — use
callouts or captions.
When you use graphics or images, try to avoid
those that are specific to cultures, genders or
religions; their meanings and interpretations
may vary between countries.
If possible, supply your localisation provider
with a list of the graphics contained in your
main document; indicate which ones contain
text, which pages they are on and where the
files can be found.
When providing the original graphics, give your
localisation provider the following basic design
information: fonts used, export or save settings,
colour information, and any design specifications
used to create the original graphics.
Pay attention to graphic and text formatting.
Make the text CAT-tool friendly by keeping it
in text boxes and ensuring there are no hard
returns within the paragraph.
Develop a long-term strategic partnership
with your localisation provider. The more
projects your provider completes, the
more familiar they will become with your
organisation, products and processes. You
will ultimately save money and improve the
overall quality of your localisation projects.
Work with your localisation provider to
develop a graphics ‘style guide’ to establish
guidelines for graphic creation, use and
localisation. This will help to ensure
consistent content creation and to optimise
delivery schedules and budgets for
localisation projects. C
Elaine Abbott has worked at Lloyd International
Translations for seven years as a Desktop Publishing
(DTP) specialist. She has extensive experience in DTP
having worked in the translation industry since 1989.
W: www.lloyd.co.uk
Sue Rigby has worked in the translation and DTP
industry for over 15 years. She started her career
as a translator at Lloyd International Translations,
translating French and Spanish to English. Sue now
specialises in DTP.
W: www.lloyd.co.uk
Translation specialists
in your world
At Lloyd International Translations, we will:
• Reflect the quality of your products
across all languages
• Reduce your costs
• Help you succeed globally
• Be your localization partner: software,
technical documents, web and marketing
Providing first-class translations since 1989
www.lloyd.co.uk
+44 (0)1829 730050 [email protected]
26 Project profile
Enjoying your work right into retirement
Technical illustrator, Douglas Newton, has kept his skills sharp by
producing a cutaway illustration of his own 1950 Bentley Mk VI.
I am a retired technical illustrator, a member
of the ISTC since 1985 and also a member of
the ISTC Council in the early 1990s. As there
have been no articles on the subject of technical
illustration in Communicator recently, I thought
readers might be interested in a project that I
undertook last year.
My background
Let me begin by telling you a little about myself
and my career. I started out in the late 1950s,
not as an illustrator but as a junior draughtsman
at Cotton & White, a small contract design
company based in Walton-on-Thames in Surrey.
Cotton & White had two drawing offices in
Walton and employed around 50 draughtsmen
working on various mechanical and electrical
design projects. The company also had a shop
that sold graphics and drawing office equipment,
as well as providing a dyeline printing service.
As a junior, I was expected to make the tea
and run errands for the senior draughtsman; I
also ran off prints for them using the dyeline
machine. My training was comprehensive,
from grades of pencils to understanding and
interpreting orthographic plans, elevations and
sections. I also learned about various engineering
components, processes and tools.
After three years, I left Cotton & White to
pursue a career in technical illustration and was
fortunate to be taken on as a trainee technical
illustrator with the Vickers Armstrong Aircraft
Company in Weybridge, Surrey. After a few
months, Vickers was taken over and became
the British Aircraft Corporation (later renamed
British Aerospace). I was employed in the
technical publications drawing office for 18
years. During that time, some of my technical
illustrations for the Concorde supersonic
airliner were displayed in the Science Museum,
London. Most of the aircraft factory premises
and offices at the Weybridge site no longer
exist but the famous ‘club house’ now houses
Brooklands Museum.
I went on to be employed as a senior technical
illustrator by first Data Recording and then
Bechtel. My most exciting project came during
my time at Bechtel, a privately owned American
company with an office in West London that
provides engineering, construction and project
management to clients around the world (its
first megaproject was the Hoover Dam).
The billion-pound project, for Conoco (known
for its Jet-brand petrol), was for the world’s
first tension leg platform (TLP) in the Hutton
Field in the North Sea. The platform was held in
position by cables tethered at each corner and
secured to piles driven deep into the seabed.
Bechtel managed the project and provided
specialist personnel from various disciplines,
including a small graphics team in which I was
the only illustrator.
My job was to create complex hand-drawn
technical illustrations to show the structures
used in the platform. Conoco’s management team
used my illustrations to monitor progress during
the three-year build phase, printing them in
colour in the monthly management reports. Many
were also reproduced (with Conoco’s permission)
in professional magazines for mechanical, marine
and structural engineers. Those were great days
with long working hours, lots of buzz and visits
to the fabrication site in Scotland. The work
was complex and exciting, all produced with
engineering drawings as the only reference.
I eventually left Bechtel to start my own
technical artwork company and traded as a
one-man company for 25 years, providing
technical artwork services to several blue-chip
clients in the aircraft and oil industries. I retired
a few years ago, after 45 years as a technical
illustrator, and now run a car-hire business for
weddings called Elegant Cars. This keeps me
busy throughout the year and is a good way to
capitalise on my lifetime passion for vintage
and classic cars.
My project
Now that I’m retired, I’m free to pursue projects
that particularly interest me. I’m a vintage and
classic car enthusiast and so I’ve produced the
hand-drawn cutaway technical illustration of my
1950 Bentley Mk VI, shown on the cover of this
issue. I’ve owned the car for eight years, after
buying it from a friend as a running restoration
and spending both time and money on bringing
it to its present condition.
I created the illustration shown here in the
traditional way, which is to say that I started by
using a pencil on tracing paper and then traced
the result in ink on drafting film. I created
and scaled the illustration using a three-point
perspective grid. Finally, I traced the completed
pencil drawing onto drafting film using a
Rotring Rapidograph pen.
The most difficult, and time-consuming, task
was researching the project. It is very important
to gather together all the necessary reference
information before starting work. I began by
photographing a Bentley chassis and running
gear with the body off; I used an enlarged
print of this photograph as a guide for the
27
© Douglas Newton 2009
Cutaway illustration of a Bentley MK VI created
using traditional tools and techniques
detail. I then obtained copies of engineering
chassis drawings belonging to Bentley Motors
and used these as reference for the detail,
dimensions and scaling of the illustration. The
Rolls Royce Enthusiast Club (RREC) was a great
help: the chassis was in its workshop and the
drawings were in its archive. When I had drawn
the chassis, wheels, suspension and engine,
I photographed my own Bentley and used an
enlarged print of the photograph to trace the
body outline; I then matched this to the chassis.
It took me around six weeks to complete the
project, including the time taken to source the
engineering drawings and photographs.
My original artwork is A0 size
(1189 × 841mm). I had this scanned with an A0
drum scanner and the image saved to a CD for
professional printing.
My sales drive
I created this illustration for my own
satisfaction, as a retirement project and as a
way to keep my skills sharp. Once I’d completed
the artwork, my family and friends all suggested
I market copies of the illustration as limitededition prints.
This became an interesting extension to the
illustration project. I e‑mailed every vintage and
The Bentley Mk VI
After the Second World War, Rolls-Royce recognised the changing
requirements of its clients, which included a shift away from chauffeur-driven
cars to owner-driver saloons. The first all-new model was the Bentley Mk VI of
1946. It was designed to be as compact as possible because of steel rationing.
It was powered by a new engine from a new family of Rolls-Royce power
plants, the 4257cc B60, which had twin SU carburettor, overhead inlet valves
and side exhaust valves. It broke with tradition by being the first Rolls-Royce
or Bentley to have a standard body design. The four-door body was produced
by Pressed Steel and the cars were hand-built at the new Rolls-Royce factory
in Crewe, Cheshire. Separate chassis could still be purchased for specialbodied cars. All cars had manual gearboxes with floor changes mounted
on the right-hand side. All standard cars featured sliding steel sunroofs and
many other period fittings. About 4,800 Bentley Mk VI cars were made. The
Mk VI was eventually replaced in 1953 by the long-booted R-Type saloon.
classic car magazine editor who I thought might
be interested, attaching a low-resolution version
of the illustration and a short description
of how I’d produced it. Almost all of them
published both the illustration and text free of
charge.
I continued my marketing by contacting the
motoring editor of the Daily Telegraph. He
was enthusiastic and published the illustration
and profile online. I also visited the RREC
and the Bentley Drivers Club (BDC), both of
28 Project profile
which published the material in their club
magazines — again free of charge.
In the meantime, I researched companies that
could produce A2 prints using lightfast inks on
acid-free 260gsm art paper. Having negotiated
a price per print, I was ready to receive orders.
I set a sale price of £80, excluding postage and
packing. However, in recognition of the help
that the RREC and BDC had given me, I donated
framed prints to be hung in their prestigious
club headquarters.
As a result of all my marketing, I have so
far provided 28 enthusiasts with limitededition prints accompanied by a certificate of
authenticity and a brief profile of myself. As
well as many sales in the UK, I’ve posted prints
to enthusiasts in Canada, Australia, Finland,
Sweden, Luxembourg and Ireland.
Last year, I attended a conducted tour
of Bentley Motors’ factory at Crewe
with the RREC. While there, I visited the
museum. Displayed there are early Bentleys
alongside the very latest models, together
with technical drawings and photographs.
Reflecting on this visit, I wondered if Bentley
Motors might like to buy one of my limitededition prints and so I wrote to the Marketing
Director. Several weeks later, I received a
letter saying that Bentley Motors wanted to
order a print. I was delighted and despatched
it the very next day.
The Bentley Drivers Club is staging a Bentley
Mk VI exhibition in June this year and has asked
me if they can display a copy of my illustration
as a centrepiece. It will also be on the cover of
the Bentley Drivers Club Review.
The Bentley MK VI at work for Elegant Cars
My plans
This project has given me great satisfaction.
My most pleasing moment was standing back
and looking at my completed illustration. It is
unique! When orders began to arrive in response
to my marketing activities, I felt very proud that
people wanted to own a copy of my work.
I am now considering starting another
hand-drawn cutaway illustration. Perhaps this
time I might draw a Rolls-Royce, provided I can
obtain suitable reference material such as
engineering drawings and photographs. I am
deliberating between a 1930s 20/25 saloon and
a 1950s Silver Cloud. C
For more information
Bentley Drivers Club — www.bdcl.org
Bentley Motors — www.bentleymotors.com
Brooklands Museum
www.brooklandsmuseum.com
Rolls-Royce Enthusiasts’ Club
www.rrec.org.uk
Royal Egham Show
www.eghamroyalshow.org.uk
Douglas Newton MISTC is a member of the RollsRoyce Enthusiasts Club and President of the Egham
Royal Show in Surrey. He has organised the Vintage
Vehicle Section of the show for 30 years.
W: www.elegantweddingcars.co.uk
29
Tools
MadCap Flare goes mobile
Neil Perlin of Hyper/Word Services explores the key new
functionality offered by version 6 of this authoring tool.
The mobile space
Difficult development environment
The mobile information space came into
existence in the late 1980s with Apple’s Newton,
followed later by Microsoft Windows CE,
Wireless Markup Language (WML) and other
mobile products, languages and standards. For
several reasons that I will discuss briefly below,
none did well in the mass market; they have
become footnotes in the history of computing.
But vendors continue to enter the mobile space
because that space follows societal trends
toward mobility.
MadCap Software’s WebHelp Mobile target,
introduced in Flare 6, is one of the new entrants
in the mobile space. In this article, I will outline
the problems that hindered the development
of that space, and technical and marketing
changes that are correcting those problems. I
will then relate those changes specifically to
Flare’s WebHelp Mobile output.
For the purposes of this article, I will
postulate that past efforts in the mobile space
failed for three primary reasons: an uninviting
interface, a difficult development environment,
and ‘silo-ing’.
The code sample shown in Figure 3 comes from
that same 1998 presentation mentioned above.
GUI tools were crude in 1998, so developers
often had to hand-code. The code itself wasn’t
that difficult, but any hand-coding is slow and
subject to typographical errors and deviations
from good syntax.
Uninviting interface
The screen in Figure 1 is from a presentation
that I gave in 1998 on the subject of using WML
to create mobile websites. This was largely
how the interface looked — not very inviting
by today’s standards or even those of the
day. Users might have accepted such a bland
interface if mobile had appeared in the early
1990s, when much of the web itself looked like
this. But by the late 1990s, the ‘real’ web had
improved so much that the mobile web looked
prehistoric. Today, that’s no longer a problem
when mobile information can look like the
screen shown in Figure 2.
Figure 1. 1998 mobile interface
Silo-ing
Until Microsoft introduced HTML Help in 1997,
online help and the web, including the mobile
space, were generally viewed as two completely
different spaces with different languages, tools
and standards. So help developers couldn’t
easily create mobile outputs as part of their
regular work.
Flare 6’s mobile output
Flare 6’s features largely eliminate the problems
in the earlier mobile space.
The WebHelp Mobile target definition and
control are integrated into Flare’s interface,
largely via the Targets and Skins folders on
the Project Organizer. This eliminates the silo
problem; mobile is now just another output
from a tool that you already have and know
how to use.
The integration into Flare’s GUI environment
means there’s no hand-coding unless you
Figure 2. 2010 mobile interface
30 Tools
want to do something unusual. This reduces
the risk of typos and non-standard syntax.
WebHelp Mobile can technically convert
almost any feature in a standard Flare
project to mobile. (This is not quite true
when it comes to design, as I will discuss
below.) This means your mobile information
has essentially unlimited design options,
eliminating the blandness of the interface.
Flare 6 has other interesting attributes for the
mobile space:
WebHelp Mobile uses a ‘mobile site’ model
rather than a ‘mobile app’ model. It is not
tailored to any specific device; instead, it is
just a website accessible from any device
with a microbrowser. This eliminates the
sometimes difficult problem of selecting the
device(s) to which to output.
The code is ‘pared-down’ XHTML, according to
MadCap. This means it is open-source.
WebHelp Mobile automatically adapts its
features to those supported by specific
microbrowsers on specific devices. If there
is no JavaScript support, for example, there
is no search capability (the Search box won’t
even appear in the output) or dynamic text
functionality (drop-down links, expanding
links, and togglers display fully expanded),
and the Home button looks different. With
JavaScript support, all these features are
available, plus some others like navigation
arrows. This automatic adaptation to the
display device’s capabilities simplifies project
planning, design and management because
you do not have to create a separate output
for each device.
WebHelp Mobile uses several pre-defined
and mobile-optimised skins. This makes skin
definition simply a matter of pointing and
clicking, like defining a regular skin.
MadCap added a single-page, generic emulator
Figure 3. Coding for a mobile interface in 1998
to preview WebHelp Mobile, as shown in
Figure 4. The preview is generic, rather than
tied to a specific device or output format.
All standard navigation options are available
on the home page, as shown in Figure 5 for
the table of contents, index, search and About
features.
The result is a fully functional and deviceindependent mobile authoring tool packaged
inside the larger Flare tool.
How well does it work?
Flare is a single-sourcing authoring tool, which
means that you should be able to convert any
project to the WebHelp Mobile target. I set out
to test whether this was the case.
I created a small project with a standard set
of features that would appear in a standard
project. Converting this project worked well
technically. Text, heads, images, hyperlinks,
external hyperlinks and Flash (SWF) files all
converted well. The only feature that did not
was a popup, which turned into a hyperlink
when converted to mobile. Technical support
noted that this was due to the need to create
the lowest common denominator set of features
to be sure the output would run on as many
devices as possible, some of which do not
support popups.
In fact, all the technical issues that I found
in the test seem to stem from display device
limitations. For example, WebHelp Mobile
should be able to use a regular project’s header
and alias files to create context-sensitive help
for mobile applications, but the device must
support multitasking or else opening the help
closes the application.
Where my test did reveal problems was in
converting the design from a large-screen
format to the tiny screen of a mobile device.
This is not a flaw in WebHelp Mobile but
31
simply due to the extreme differences in the
display devices. Text and variables (which are
themselves text) converted with no trouble
because they can reflow to fit the different
screen sizes. Although elements that were
too wide or too big converted, they added
horizontal and/or vertical scrolling. Scrolling
isn’t necessarily evil, but it does reduce
usability. Elements with this problem included
tables, graphics, drop-downs and togglers that
included tables and graphics, master pages,
wide head styles and SWF files. Snippets and
project import link items can also be difficult
because you won’t actually ‘see’ them as you
insert them, so you may not realise that they’re
too large — basically ‘out of sight, out of mind.’
Finally, there’s the information design
problem of having to choose between
information that’s ‘must have’ versus ‘nice to
have’, and removing the latter from the mobile
output.
In effect, think of WebHelp Mobile output as
an extreme example of single sourcing. You’ll
have to make extensive use of conditionality to
handle this. There’s an interesting case study
from an Australian company called Thinking
Windows at www.madcapsoftware.com/
casestudy/ThinkingWindows.aspx.
Figure 4. Preview displayed by emulator
Summary
The most important aspect of the WebHelp
Mobile target is strategic: it lets you try mobile
without having to buy and learn a new tool.
And if mobile proves not to be what you need,
backing out is simple and free: delete the
WebHelp Mobile target and go back to your
regular outputs.
Mobile information may not be in your
information strategy now. But as society and
business become more mobile, it should be on
your list of things to investigate and keep
abreast of. If you own Flare, WebHelp Mobile
makes that easy to do. You’re likely to find that
supporting mobile will complicate the job of
designing and presenting information, but it
will also add an enjoyable intellectual challenge
to your work. C
Neil Perlin has 31 years’ experience in technical
communication, with 25 in training, consultancy
and development for WinHelp, HTML Help, CE Help,
WebHelp, RoboHelp, Flare and others. Neil is a columnist
and speaker for STC and IEEE PCS and an STC Fellow.
W: www.hyperword.com
Figure 5. Standard navigation options
32 Project profile
Migrating to MadCap Flare
Adrian Morse describes how his company left the familiar
waters of Adobe products for the open seas of Flare.
The date had arrived. After countless group
discussions, numerous trials and an ongoing
effort to separate the facts from the hype, we
decided to replace Adobe’s FrameMaker with
MadCap’s Flare. Actually, it was more like
replacing ‘FrameMaker plus Acrobat plus Mif2go
plus a little bit of RoboHelp’ with MadCap Flare.
FrameMaker had long been our source. From
there we had been kicking out PDF files via
Acrobat and HTML Help files via Mif2go. It was
as close to single sourcing as you could get: a
few clicks and we had the outputs, with no postediting whatsoever. The help system for one of
our products needed to be in WebHelp format; we
already had some RoboHelp (for Word) licences
so decided to just use it as a backend converter,
taking Mif2go’s HTML output and converting it to
WebHelp format. It all seemed to work well…
If it ain’t broke…
Our company had been through various
mergers, each bringing its own styles,
formats and functionality along for the ride.
Our product suite had also expanded from
client/server to browser-based applications.
Individually, the documents and help systems
were straightforward to create and they did
the job. Globally, however, it was a mess; it
looked as if we were still separate companies.
Something had to be done.
Our first step in rectifying the situation was
to decide on a common format for the help
systems, and we chose WebHelp. Besides it
being the only real contender for the browserbased products, our experience was that users
felt more comfortable navigating such systems.
Next we had to decide on the tool. Having
experienced occasional problems creating new
projects with Mif2go, we decided to look at
alternatives rather than use it together with
RoboHelp (for HTML to WebHelp conversion).
At this stage it would have been natural to
evaluate Adobe’s Technical Communication
Suite, but our technical communicators
had had so many negative experiences with
previous attempts to integrate FrameMaker and
RoboHelp that (rightly or wrongly) the idea was
quickly dismissed. By contrast, there was some
zeal for MadCap Flare which eventually won
us over. This article describes how we took the
plunge and migrated to it.
Decisions, decisions …
We soon found out just how immense Flare is.
Coffee-room discussions overflowed with terms
like ‘snippets’ and ‘togglers’. Team members
involved with creating templates began to
look rather haggard. Others were waiting for
guidance. It became clear that the strength
that was the product’s versatility was also a
weakness for those new to it.
So what if it’s XML based?
MadCap is keen to tell us that Flare is ‘XML
based’, so that must be a good thing, right?
Well, yes, but…
As far as our final PDF and help files were
concerned, it did seem that Flare could
not really ‘do’ anything that our previous
combination of tools could not; it just achieved
the same end result by different means. For
example, applying a format to a paragraph
became applying a tag to an XML element,
opening the table catalog became opening the
table style sheet.
For XML or DITA outputs, there are likely
advantages to authoring within XML itself but
for us this did not seem to make a difference.
Sure, we could look at the XML behind a topic
but we only really had cause to do so when
trying to distinguish a bug from ‘by design’
behaviour.
Perhaps one exception to this observation
is the ability to easily apply DIV tags across
multiple paragraphs in a topic. As well as
being needed for dynamic HTML effects, DIV
tags offer a way to control the look of sections
rather than individual paragraphs or entire
topics. For example, you can easily apply a
coloured background to selected text (Figure 1).
What’s up doc?
The first time we opened a Flare project we
were hit by an ‘okay, so now what do I do?’
feeling. In fact, for the first few weeks, it
happened pretty much every time we opened a
project. However, the situation improved after
we had assimilated the following:
1. We were accustomed to seeing a FrameMaker
‘book’, in which the main sections of the
document or help system were clearly
visible. It took a while to realise that the
Flare TOC was now the first port of call. It is
a little irritating that the TOC does not open
by default but this can be mitigated to some
extent by configuring Flare to reload open
files when you open a project.
2. We were accustomed to working with a
dozen or so filenames in a logical order. In
contrast, our Flare projects typically had
well over 100 files ordered alphabetically
with no indication of where they slotted into
33
the document… welcome to topic-based
authoring! The granularity of files was
driven by the look and feel we wanted in the
help system. MadCap’s suggestion of ‘make
every topic self-contained’ sounds like good
advice and would certainly have reduced
the file count, but it did not really work for
us. Anyway, despite the paradigm shift in
the way of working, a few months down the
line and the technical communicators didn’t
really bat an eyelid anymore. They just made
sure to link any new file to the TOC as soon
as it was created.
Drag-and-flop
Getting to grips with Flare was made harder
by minor annoyances in the interface. I use the
word minor because the issues we hit had easy
workarounds. Here are a handful of quirks to
expect:
Drag and drop can sometimes be a little
tricky. If you select a whole line of text but do
not include the carriage-return symbol you
can drag the selection and drop it elsewhere,
such as within another paragraph. However,
the carriage-return symbol sometimes gets
selected automatically right at the moment
that you attempt to drag the selection. Flare
then decides that you are trying to drop
one XML element inside another, which is
prohibited and so the ‘drop’ fails. Nothing
that Ctrl-X and Ctrl-C won’t sort out though.
To insert a paragraph above a heading you
put the cursor in the heading, press Home
to move the cursor to the start of the line
and then press Enter, right? Wrong! If you do
this, the heading’s tag changes to a <p> tag
and you have to reapply the heading. This
annoying behaviour only seems to happen
with headings. For example, if you use this
method to add a new paragraph above
a bulleted item, the bullets are retained.
Fortunately, there is an alternative: after
pressing Home, you can press ↑ (which makes
the cursor horizontal above the heading)
before you press Enter.
You can copy the contents of one table
cell and paste them into another, but you
cannot paste the contents of a single cell into
multiple cells at once.
FrameMaker and just import into Flare in order
to create the help output. Our decision was
primarily influenced by two factors:
We wanted to come as close to a 100% singlesourcing workflow as we could.
We wanted to be able to take advantage of
Flare’s great features for adding dynamic
HTML effects (such as drop-down text or
popups).
There then followed the usual group
discussions about what 100% single sourcing
means. We concluded that it meant the ability
to make changes in the source and create
immediate outputs without any post-editing
of the outputs being needed. This ruled out
authoring within FrameMaker since dynamic
HTML effects added in Flare after importing
from FrameMaker would need to be recreated if
the source was later changed and reimported.
PDF output from Flare… are you serious?
Flare v3 did not have support for directly
creating PDF files, so we initially output to
FrameMaker and then generated PDF files from
there.
When support for PDF was added in version 4,
we were very sceptical. MadCap were new
players in the field and we could not see how
they could compete with the very company that
created PDF technology. We needn’t have been
concerned. PDF files from Flare looked great. A
month down the line and we had recreated our
templates, bypassing FrameMaker and Acrobat
completely.
Lists
Out of the box, Flare lets you apply bullets and
numbered lists to text using the drop-down
control on the toolbar. In the background, <ul>
and <ol> tags are applied. Our next decision
was whether to use these innate list styles or
create our own auto-numbered styles (just as in
FrameMaker).
You can get a long way with the innate tags
but they have their limitations. For example,
they cannot show chapter, section or volume
numbering and they cannot be used with
custom bullets. You also need to restart new
lists manually and there is no inherent ‘control’
over what type of bullets or numbers each
technical author on a team uses. Autonumbered
Spoilt for choice
Getting started with Flare can be quite daunting
due to the proliferation of options at every
stage. Here I describe some of the key choices
we found ourselves making. They are presented
in order of importance. This information by no
means covers all functionality available in Flare,
just the main areas where decisions are needed.
Source?
Our first big decision was whether to author
entirely within Flare or continue with
Figure 1. A DIV tag class applied to text. In the CSS, this class is configured to give
a blue background.
34 Project profile
TOC) and an index as well as entries for topics
(Figure 2).
Decision time again. Should we create the help
and PDF outputs from two different project
TOCs? Or should we stick with one project
TOC but use ‘conditions’ to hide any printrelated entries when creating a help output?
(For instance, the condition ‘print only’ could
be applied to the cover page entry to exclude it
from the WebHelp.)
As far as the end product was concerned
both strategies were the same. However, taking
maintainability into account, we decided to use
a single TOC with conditions. In our case, most
content updates were likely to affect both print
and help outputs. Having one TOC meant that
we would only have to link the TOC to a new
topic once. Using two TOCs would have meant
linking each new topic twice and there was a
risk of inconsistency between the TOCs.
Figure 2. A ‘project TOC’ with ‘print only’ conditions applied to the cover and
copyright page, TOC and index
…the whole
program is oriented
around the concept
of a single stylesheet
styles do not suffer from these deficiencies, so
we decided to use them instead.
At this stage, we could have created the
autonumbered styles as CSS classes for the
ordered list tag. For example, ol.numbers
(where ol is the tag and numbers is the class).
Instead, we chose to create them as classes for
the <p> tag (that is, p.numbers). Why? Well,
some windows and controls in Flare only show
classes that are pertinent to the selected style.
For example, suppose you are editing a list
item and want to change its style to a certain
paragraph class. You are not able to select
the paragraph class from a drop-down list of
styles because the list will only show classes
appropriate to list tags (such as li.bullet). So you
first have to remove the list tag, adding extra
steps to the operation. On the other hand, if you
stick to paragraph classes for all styles, you will
always have both list and non-list styles within
easy reach. There is nothing about list classes
that you cannot achieve through a suitably
configured paragraph class.
The project TOC
It is useful to distinguish a ‘project TOC’ from
a ‘print TOC’. A project TOC determines the
topics that will be included in the output, their
order and hierarchy. For help outputs, the
project TOC corresponds with the actual TOC
seen in the resulting help system. By contrast,
in print outputs it is the print TOC that appears
rather than the project TOC.
A project can have one or more project
TOCs. When you build an output you define the
project TOC to use. For printed outputs, the
project TOC needs an entry for a cover page, a
print TOC ‘proxy’ (a placeholder for the print
The print TOC
There are two ways to create a print TOC:
Replicate the structure seen in the associated
project TOC
Define the styles that you want to be TOC
entries (for example, all H1s and H2s).
Basing the print TOC on the project TOC has the
advantage that you can instantly see how your
TOC will look. However, we decided to go for
the option of using styles because it effectively
encourages consistent formatting for the
same heading level. For example, if you want
a heading to appear at the usual H3 level, you
must apply a H3 style to it.
Table styles
You can apply styles to tables either by using
table stylesheets or by applying <table>, <td>,
<tr> and <th> tags or classes from the usual
project stylesheet (there can be issues if you try
to mix the two methods).
We opted for table stylesheets for the
following reasons:
It’s easier to create tables with them.
You can tab to add a new row.
It’s easier to set up alternating row formats.
They avoid a bug that occurs when ‘undoing’
a <tr> style application.
That said, table tags or classes can be needed
for complex tables so perhaps a common-sense
approach would be to set up table stylesheets
initially and only create table classes if a
particular situation calls for them.
Then there are indented tables that you might
need for lists or other situations. Again, you
have a choice to make: either create an indented
table style or use an existing table style but edit
the left margin after applying it. We decided to
create specific styles because margin edits are
not retained if a table style is reapplied or if an
additional table style for print output is later
applied to the table.
35
Localising WebHelp skins
The method for localising a WebHelp ‘skin’
depends on whether the English skin uses
default text or has been customised. If it uses
default text, you just need to substitute the
skin provided for the appropriate language.
However, if your English skin has custom text
(for example, if you change the tooltip for a
button on your WebHelp toolbar) and you want
the tooltip to be localised too, another approach
is needed. You have these options:
Customise each language skin to match the
English skin changes. One difficulty here is that
language skins are stored under the ‘Documents
and Settings’ folder for each user (that is,
outside the Flare project folder). So you have
to remember to include this file when sending
the project for localisation and the localisation
agency needs to make sure they place the file in
the expected path for each user.
Forget language skins and just use a a copied
and renamed version of your English skin. If
you do this, you must remember to change the
skin link in the target for each localised project.
Stylesheet policy
Flare lets you use the same stylesheet for
different outputs or specify a different
stylesheet for each output. This one was a
no-brainer: the whole program is oriented
around the concept of a single stylesheet with
‘print’, ‘non-print’ and ‘default’ media sections.
You link each output to the medium you want.
(For example, you would link a PDF output to the
‘print’ medium.) When using a single stylesheet
in this way, Flare enables you to see easily how a
topic is going to appear for each output and the
effort needed to maintain styles is reduced.
We found it best to avoid using the ‘non-print’
medium and instead define all styles in the
‘default’ medium section of the stylesheet first,
with the ‘print’ media section just being used
for any changes from the default. This ensures
that all styles are available regardless of the
media set for viewing and it also makes it easier
to configure new styles.
We also found it to be a good idea not to set
a default font size for the <p> tag but instead
set a default font size for the <body> and
<td> tags. It meant that we could set our <p>
styles to drop down a font size automatically
when used inside tables, avoiding us having to
create a whole set of styles for use in tables. For
example, our p.Bullets style normally appears
with a font size of 10pt, but when used in a
table it automatically becomes 9pt.
Policy for resizing screenshots
As well as Flare, we also purchased MadCap
Capture for working with screenshots. Flare
alone offers various ways to resize screenshots:
throw Capture into the mix and you have even
more options, which can get a little confusing.
We needed a policy.
We first spent time testing the quality of
images that we had reduced in size and noted
that some resizing methods worked better than
others. We looked at both PDF and help outputs.
Our expectations for the quality of resized
images in PDFs were high but we did not expect
to see high-quality resized images in help output,
since any reduction necessitates a loss of pixels.
However, we were pleasantly surprised. With
our previous workflow, we could only achieve
acceptable results by making sure that any
screenshots in the HTML output were recreated
at their original size. They were crisp and clear
on screen, but the larger screenshots could be
overbearing. With Flare, this wasn’t necessary. As
long as the option Generate copies of resized
images was selected we could reduce screenshots
down to about 65% of their size and still find
them acceptable in the help file. As Flare does not
claim to be a graphic editing tool, we found this
remarkable. It opened the door to using the same
image dimensions for both PDF and help outputs
for the majority of images. Doing this wasn’t
strictly necessary, as Flare allows you to specify
separate dimensions for online and print output,
but it certainly made things easier.
As for how to resize, the following methods
are available in Flare:
Dragging an image’s borders
Setting dimensions for an image
Setting maximum and minimum image
dimensions for all images in the project using
the stylesheet.
We found that all methods produced good
results. However, you cannot size an image
by a scale factor or DPI in Flare; if you want
to do that, you have to calculate and enter the
dimensions yourself. Or you can use Capture.
We observed that the Print DPI setting in
Capture worked well but the Print Size setting
(which one would assume should be reciprocally
linked to the Print DPI setting) did not; it gave
a low-quality image. In Flare, as I mentioned
previously, we could set the same dimensions
for online and print outputs in one place and
get good quality outputs. In Capture, this did
not work: the quality of the online image was
as expected but images in the PDF output were
of poor quality. Print settings always had to be
specifically configured in order to get a goodquality image.
Because of these issues, we decided to do
all resizing in Flare rather than Capture. We
maintain a consistent scale factor by calculating
the image dimensions we need manually. A
handful of large screenshots do not look good
in the PDF output when scaled by the factor
needed for the online help. To cater for such
situations we set a maximum print image width
of six inches in the stylesheet.
I should add that MadCap has made ongoing
improvements and changes in the handling of
36 Project profile
Find/replace capabilities
Figure 3. A variable used in the footer of a page layout.
images. After each new release, we run tests
again and revise our policy as necessary.
Use of variables
Compared with
FrameMaker,
maintaining styles
in Flare projects is a
walk in the park
The big decisions were behind us. Most choices
ahead were typical of any tool, not just Flare, so
I will just comment on a few of them.
First are variables (Figure 3). To make
maintenance and localisation easier, we used
variables for headers rather than direct text in
the ‘page layouts’ (equivalent to master pages
in FrameMaker). However, we decided against
using variables for text on cover pages because
you cannot manually control line breaking
within a variable and this could have led to
localisation issues in languages such as German,
where the text length would be expected to
increase significantly.
Use of conditions
Adrian Morse is
Documentation
Manager at Picis, a
US-based provider
of information
solutions for delivery
of clinical, financial
and operational
results in hospitals.
He is responsible for
documentation and
help files, and for the
people who work on
them. His background
is scientific: he holds a
PhD in Applied Physics
and worked as an
electrical engineer and
later as a lecturer at
Manchester University
before becoming a
technical communicator
in 1997. He is an
advanced user of
FrameMaker and Flare,
and has also been
involved in numerous
localisation projects
(he is fluent in Spanish).
E: Adrian_Morse@picis.
com
W: www.linkedin.com/
in/adrianmorse
Conditions can be applied to individual
letters, words, sentences or entire paragraphs.
A policy was needed to ensure consistent
usage. The localisation agency asked that we
apply conditions only to entire sentences or
paragraphs, not to individual words (with the
exception of table headings). We get some
repetition of source content this way, but it is
easier to work with.
We also decided that conditioned paragraphs
should include the paragraph mark at the end.
(If it is included in some cases but not others,
outputs might have sentences running into each
other or empty paragraphs.) The important
thing here was consistency; a policy of leaving
out the paragraph mark would have been
equally valid.
FrameMaker features we miss
Automatic markup
Start typing in FrameMaker and you can see
a bar in the margin next to any text that has
changed. Change bars are visible in the PDF
output; this enables us to use an Acrobat shared
review process, which we need for regulatory
purposes and which reviewers seem to love.
Flare, on the other hand, offers the technical
communicator a way to see the differences
between a topic and an earlier backup of
it but reviewers cannot see this view. As a
workaround, we apply highlighting manually to
mark text that has changed before generating
the PDF file. This is laborious and error-prone.
Find and replace in Flare can be confusing as
there are two similar windows for this purpose.
Searching in one window creates a list of topics
that contain the search term; searching in
the other opens the next topic containing an
occurrence of the search term.
Besides the comparative simplicity
of FrameMaker’s Find/Change window
functionality there is also a noticeable
difference in search options. Flare does not
offer searches such as the following that can be
found in FrameMaker:
Character tags (spans in Flare)
Paragraph tags (tags and classes in Flare)
Character formats (such as italic and bold
together)
Any cross-reference
Cross-reference of format
Unresolved cross-reference
Any table
Table tag (a particular table style in Flare)
Conditional text
Anchored frame (just images in Flare).
You can search for some of these entities in
Flare by searching in the source code for the
tags you expect but this is undocumented and
rather risky, especially for ‘replace’ operations.
For some searches across topic files, we
therefore find ourselves resorting to FrontPage.
It should be said that you can generate certain
reports including the following:
A list of topics that contain images
For each image, a list of topics in which it is
used
A list of topics in which a condition is applied
to text (but with no indication of what the text
or the condition is — this could be a bug)
For each variable, a list of topics (and
templates) in which the variable is used.
However, these reports only list file names and
do not provide the context in which the entity
is found. That wouldn’t be so bad if the entries
were hyperlinked but they are not (for that you
need the MadCap Analyzer add-in).
Ease of inserting rows and columns in tables
Inserting a single row or column in Flare is easy
enough but you cannot insert multiple rows or
columns from the right-click menu. To do this,
you need to use the Table Properties window
and you do not have control over where the
rows or columns are placed.
Flare features we couldn’t do without
Here I will discuss some features that did not
exist in our previous Frame plus Mif2go setup.
Global Project Linking
Compared with FrameMaker, maintaining styles
in Flare projects is a walk in the park. No risk
of users selecting the wrong format import
options. No obsolete styles hanging around
37
afterwards. No need for FrameScript add-ins to
help you out. Yes, definitely a walk in the park.
To make that walk even more pleasant, Flare
offers a feature called Global Project Linking.
This enables you to have templates propagated
to all Flare projects in your workplace from a
central location. You can also use Global Project
Linking for sharing topic files between projects
automatically… as soon as Mary updates the
‘Basic Computing Skills’ topic, Dave and Alan
see it updated in their user guide projects! Cool.
Ease of adding dynamic HTML effects
It was possible to add dynamic HTML effects
(such as expanding text and popups) using our
previous workflow of FrameMaker plus Mif2go.
However, it meant adding raw HTML code to
markers inside FrameMaker, so wasn’t the most
user-friendly of methods. In contrast, Flare has
great functionality for adding such features.
We particularly like ‘togglers’, a feature that
lets you show and hide entire sections within
your topic (and they don’t even have to be
contiguous).
Integration with Capture
Whenever you create or open a graphic file in
Capture it creates a properties (.props) file in
the same folder. If you add callouts to an image
they get added directly to the image file (for
example, to the PNG file). However, the props
file effectively contains the original graphic plus
all the changes that have been made. So, when
you open an image file in Capture any callout
that you added is an editable layer rather than a
merged and uneditable part of the graphic.
This is a clever design. It means that to edit
callouts in a graphic that is part of your Flare
project you just need to right-click the graphic
in the Flare topic, select Edit with MadCap
Capture, edit the callouts and save the file.
In contrast, if you want to edit the callouts in
another graphics editor, you have to maintain a
separate ‘master’ version of the file for future
editing and save any updated image file into the
Flare project.
The support
A discussion of MadCap Flare would not be
complete without reference to the fantastic
support available for it. You can easily submit
bug reports and enhancement requests through
the MadCap website. This is not like sending
information into a black hole; unlike some other
vendors, MadCap goes to great lengths to listen
to its customers and act on suggestions.
Besides MadCap’s own support system
there is a vibrant and extremely helpful user
community at http://forums.madcapsoftware.
com/index.php. Common words (such as CSS)
are ignored in forum searches but we found
that you can work around this by searching
with Google (use www.google.com/advanced_
search?hl=en and enter
‘forums.madcapsoftware.
com’ in the Search within a
site or domain field).
Conclusion
Although we have made
a few sacrifices along the
way (notably the loss of
automatic markup), our
migration has gone well.
Setting up templates took
longer than we expected due
to the numerous and often
interconnected decisions
needed. The steepness of
the learning curve was also
a bit of a shock. However,
the technical communicators
in the group are now quite
confident with Flare and
can quickly turn out new
projects. What’s more, with
regular product updates
and MadCap’s engagement
with the customer, we really
feel we have invested in a
product with great potential.
We look forward to what the
future brings.
A parting word of advice to
potential users? Flare is an
ocean of possibilities… focus
on replicating the familiar
territory of your existing
help system before sailing
off into uncharted waters! C
The Conference for
Software User Assistance
Professionals
16-17th September, 2010
Stockholm, Sweden
Sessions include:

Social Web Strategies for Documentation

Future User Assistance Trends

The Wonders of SVG

Comparison of Help Authoring Tools

Developing a Content Strategy

Optimising the “Googleability” of Your
User Assistance

Case Study: Design of User Assistance
on Mobile Enterprise Applications

What Kind of Assistance Do Users
Really Need?

Climbing the Levels of Collaboration

Writing for Readers Who Can't Read
Optional DITA track includes:

Update on DITA Tools and Best Practices

Case Study: Using DITA to Implement
Writing Patterns for User Assistance

Single-sourcing Tooltips from DITA
Keynote speaker:

Anne Gentle,
author of the popular
book Conversation
and Community:
The Social Web for
Documentation
Other speakers include:
Representatives

Matthew Ellison 
from Oracle, Red

Tony Self
Gate Software,

Joe Welinske
LogMeIn, Inc.
Conference venue:
The superb Clarion Hotel Stockholm is
located just a few minutes walk from the
Gamla Stan (Stockholm's Old Town).
Full Conference Details and
Registration:
www.uaconference.eu
+44 (0)844 504 2521
Matthew Ellison
Consulting
38 Methods
Laying the foundations for success
Nicky Bleiel discusses best practices that can help to save time
and generate higher quality outputs when single sourcing.
Technical communicators have been single
sourcing projects for many years — and we
have tools that make this easy to do — but if
the project isn’t planned correctly, the outputs
produced will not be as usable and logical as
they could be. Proper planning also increases
writing efficiency, so by starting with a good
project foundation we can save time and
produce higher quality outputs.
In this article, I will discuss best practices
and methodologies for single-sourcing projects.
Using best practices helps to reduce repetition,
missing information, indecision and rework.
You will create logical documentation for
your users, no matter what the output. This
article will focus on developing software
documentation, but is applicable to any singlesourcing project.
Let’s start at the beginning:
I’d like to start by providing context. In this
discussion, the definition for single sourcing is.
Techniques used to create some combination
of documentation for:
Multiple output formats (such as a printed
manual and online help)
Multiple audiences (such as versions for
administrators and managers)
Multiple deliverables (such as user guides and
quick reference guides).
A single project can deliver all of the above with
proper planning and organisation (Figure 1).
Before any writing begins, determine the
documentation deliverables. You will probably
be creating a help system and a PDF manual as
a minimum (although if something isn’t needed
by users, don’t produce it), but you should
consider incorporating quick reference guides
and tutorials into the project. You can use
conditions (we will talk about those more later)
to output information as separate deliverables.
If these deliverables aren’t originally planned
for, they are often spun-off into separate
projects; this adds extra work later.
Topics and paradigms
Structuring and organising topics are key
to project success. Some of us write in a
traditional book format (chapters, sections
and so on), some of us write topics as separate
chunks of content. Neither is more correct
than the other; you can write either way and be
successful. Ultimately, if your project is planned
well, the end user will not know which paradigm
you used; they will just find each output logical
and the information findable.
Sorting out the content first, and creating and
using topic architectures will keep you on track
no matter which method you use.
Sorting content
To create topics that make sense in all outputs,
we first need to determine what topics we need.
After that, we can decide their structure and
order. Start by deciding what information about
your software application needs to be covered
in each of the following categories.
Housekeeping
What mandatory topics must be included?
Welcome topics, system requirements,
installation, end user licence agreements, and
support information all fall into this bucket.
Functionality
The core of your product is what it does to
solve your users’ problems. Note all of the
major functionality of your product, using
terms that users would use, not the internal
names.
Reference
Figure 1. Examples of user assistance in a single sourced software project
These topics provide information that is not
topic-based in nature, such as glossaries and
tutorials. Reference topics are not mandatory,
but can make outputs much more useful.
For example, if your product includes special
terminology, creating a glossary and linking to
definitions from the appropriate places in the
39
online help can be very helpful to users, and it
is easy to do.
Example: topic architecture for information about a dialog box
User Interface (UI)
Software documentation has another
sub-requirement: context-sensitive help within
the user interface. For this, you need to analyse
the user interface and note the dialog boxes and
other interface items that will need specific help
topics. Those topics will generally be dropped
into the functionality bucket later, but they
should start in this category so that they are
not overlooked. Special requirements (such as
embedded help) may require additional user
interface topics not normally needed.
An existing project can be reorganised using
this method. After you’ve sorted the content,
you can more clearly see what is missing… and
also what is redundant.
Creating topic architectures
Creating pre-defined topic architectures makes
it easy to structure your topics so that you
neither omit information nor repeat it in several
places within your project. If there is an existing
topic type theory you would like to use, take the
time to analyse it and adapt it for the needs of
your project.
To create topic architectures, first determine
what you need. For example, my project
included embedded help, so I needed user
interface overview topics that explained
windows, ribbons, panes and so on at a high
level. I also needed an architecture for contextsensitive help for dialog boxes. Another
architecture was needed for conceptual
overviews of major functionality. Work out what
architectures you will need and then decide
what should go in them, keeping in mind the
way the user will find them; for example, a
dialog box topic should always explain how to
open the dialog box, because the user may have
found the topic through a search. You want
users to know what they have to do and how to
get there.
When you create your topic architectures,
be sure to compare them and verify that
requirements are not repeated among them, and
that nothing is missing. You can create three
or four to start with, and add more later if you
find that you need them.
Conditions and variables
Tagging information for different uses
(conditions) enables us to create a single project
with many outputs. Creating chunks of reusable
text (variables) makes our work much more
efficient, so let’s talk about them now.
Conditions are essentially ‘markers’ that allow
you to flag specific information for different
things. Using conditions, you can mark specific
text or graphics to display only in specific
Requirements:
Breadcrumbs*
Title
‘Why do I need this dialog box?’
Optional: Important Fact (for example, right-click information)
‘How to get there’ (include button graphic)
Task(s)
Dialog box field definitions
Related Topics*
* Breadcrumbs and Related Topics are generated by the help authoring tool
but additional Related Topics can be added manually.
instances: by output type (such as HTML Help,
manual, JavaHelp), or by customised attributes
(audience or deliverable), or by a combination
of these. Attaching conditions to topics, entire
documents or chunks of text gives you quite a
bit of flexibility.
Single sourcing solely for multiple output
formats will generally not require using
conditions, unless you have specific information
that should only appear in one output. If you
write in an output-neutral way, that should not
be necessary.
Using variable text, you can manage content
in one place and reuse it across your project
because the help authoring tool will insert the
text at designated places in the final project.
If you are going to use conditions, determine
what your conditions are and create them. Note
what text is used repeatedly with your project,
and create variables for that information.
Variable text can be as short as your company
or product name, or it can be longer pieces of
text, such as descriptions of dialog box fields.
It is common for software applications to use
the same fields in several dialog boxes. Instead
of keeping that description in several different
topics, create a variable for it and insert it
where needed. If it is repeated more than once
in different contexts, it should be a variable.
40 Methods
Editing
Tips of all sorts
Naming conventions
Be consistent — standardise on a consistent heading setup that
makes sense in both online and printed outputs. Some prefer gerunds
(‘Adding, Renaming and Deleting Topics’ or ‘Inserting a Variable’)
but some don’t. The important thing is to be consistent. Try to use
terminology that the users would use, so that when they scan the table
of contents or use the search facility they find what they need quickly.
A bonus: if your online help is on the Web, your topic will surface in the
search results.
Logical output
To help your documentation read logically in both printed
and online outputs, avoid words that are specific to books or
to help systems (such as chapter, page, topic, help system and
manual). ‘Section’ is a good substitute. Don’t fall into the trap of
conditionalising this architecture of information.
A little minimalism
Only explain what your audience needs to have explained — don’t
give instructions on how to use common interface controls if
the audience doesn’t need them (for example, ‘click the arrow
keys up or down to set the line spacing’). That effort and those
words are better used explaining what the ideal spacing is, or why
you would change it. (An example from Word Help: Click 2.0, to
double-space the selected paragraph. Click 1.0 to single-space
with the spacing that is used in earlier versions of Word. Click 1.15
to single-space with the spacing that is used in Word 2007.)
Appearance of online and printed versions
Often, quite a bit of time is spent customising the way the online
and printed outputs look. Formatting is a separate issue from single
sourcing, but it is important to think about it before creating your topic
types. You are going to want to consider what styles will be used in
each topic architecture and this is a good time to make that decision.
This can be tackled by writing one book chapter or help topic,
making sure that it includes all objects and styles, with several levels
of headings, bullets, numbered tasks, tables and so on. Use greeked
text as a placeholder if complete information isn’t available (there are
greeked text generators at www.duckisland.com/GreekMachine.asp
and www.lipsum.com). Figure out what you need and don’t need in
your project, including the number of levels of headings and bulleted
lists.
One other thing to think about: topics used for context-sensitive
help on dialog boxes should use the same heading style (maybe two
different styles at most). If the help for dialog boxes has a variety of
different looks, it looks chaotic to the user.
Cross-references
You could make the choice to avoid cross-references altogether
within your text and group them all at the bottom under a single
heading such as ‘More’ or ‘Additional Information’. It makes the
copy cleaner, but since the link is not in the context of the topic,
users may not see the significance as clearly.
Save time later
Create a variable for your product name. This will make it easy to
do a quick swap if your product name changes, or if you need to
create deliverables for multiple products. This creates a little extra
work at the beginning, but can save hours later in the project
cycle.
Make graphics more targeted
Some graphics appropriate for printed output are unnecessary
or too detailed for online use. You can exclude graphics from
online help using conditions; if you still want graphics in help,
create unique, focused ones and make their condition ‘online
only’. If you are having your manual professionally printed, you
will need higher resolution than for online help but this means
larger output files. Produce one set of graphics at 300 dpi and
conditionalise those only for print output. Use 96 dpi for online
help.
Tables
Sometimes a table is the best way to make information findable
and useful. When faced with explaining concepts that have
a number of minute details, try sorting them into a table. For
example, I created a table that lists documentation outputs,
when they should be used, pros/cons, file output types and
locations, and installation notes. This information could have
been presented in a narrative, but putting it all together makes it
easier for users to find the information they need. Point all related
topics to it.
Putting it all together
Now that you know what topics you need to
create and how they should be structured, you
can create your project architecture. Put your
topics (parents) and subtopics (children) in
order. You can do this in an Excel spreadsheet,
on a legal pad, in a wiki — whatever you prefer.
Of course, different outputs could have
different project architectures, but you first
want to get all of the topics from your four
buckets into a logical order.
After you have done that, assign the
appropriate topic architecture to each topic.
Following this methodology really is easy, and
it does not have to be linear. You can work on
different pieces of the puzzle at the same time.
When working on the project architecture, you
should put topics in priority order (with the
least-used functionality lower down in the table
of contents). If you need to cut topics because
of time constraints, those will be the ones taken
care of in the next release. This is much like
using the reverse pyramid in journalism.
Overall, one of the big takeaways is that you
will find that you spend less time writing
because you know exactly what information
belongs in each topic, so nothing will be missed
or repeated. C
Nicky Bleiel is the Lead Information Developer for
Doc-To-Help. She has 16 years’ experience in technical
communication; writing and designing information
for software products in the documentation, media,
industrial automation, simulation and pharmaceutical
industries. She is a Director at Large of the Society for
Technical Communication.
W: www.doctohelp.com
B: Technical Communication Camp
http://blogs.componentone.com/CS/blogs/
techcamp/default.aspx
Doc-To-Help is the one solution for all your documentation projects. Publish as many
outputs as you need with just one project. Use Doc-To-Help’s editor, author in Microsoft
Word, or create content in an HTML editor to produce online Help for desktop use, Web
sites (NetHelp), and print-ready manuals. Automatic single-sourcing features ensure you
can publish all this from one project without re-formatting.
Doc-To-Help does it all so you can relax & enjoy your summer!
©1987-2010 ComponentOne LLC. All rights reserved. All products and brand names are trademarks and/or registered trademarks of their respective holders.
42 Tools
Structure with FM conversion tables
While FrameMaker’s conversion table functionality is not perfect, it can
help add structure to unstructured documents. Andy Lewis demonstrates.
This article examines the basic mechanics
of creating and using conversion tables to
add structure to unstructured FrameMaker
documents. It expands on Steve Rickaby’s article
First steps in structure: wrapping up in the
Spring 2008 issue of Communicator.
We will use a very simplified document
structure and Element Definition Document
(EDD). The EDD is the file in which FrameMaker
stores the rules defining the use of all the
elements used in your structure. The EDD also
contains formatting information for these
elements, either directly or via references to your
template. We will assume that you already have a
functioning EDD and a clear understanding of the
defined structure.
While we discuss adding structure to a
single document, the techniques described
are also applicable to multiple documents
and FrameMaker book files. Refer to the
documentation provided with FrameMaker for
further information.
Figure 1. Sample document
Structure overview
Figure 2. EDD definition rules
Our simplified document contains only the
following four paragraph formats: ChapterTitle,
Heading1, Heading2 and Body, as shown in
Figure 1.
Our EDD contains the following six elements:
Parent, Prelim, ChapterTitle, Section, Heading
and Para, as shown in Figure 2.
The structure defined by the EDD is
summarised by the diagram in Figure 3.
The plus sign (+) indicates that the presence of
at least one element of this kind is required for
the structure to be valid, while the asterisk (*)
indicates an optional element in the structure.
Workflow
The recommended method for creating and
using a conversion table is to follow these steps
in the order shown:
1. Generate a conversion table
2. Modify the conversion table
3. Apply the conversion table
4. Import element definitions
5. Troubleshoot
The rest of this article will follow this workflow.
FrameMaker interface variations
Figure 3. Structure overview
In FrameMaker version 7.x, access to conversion
table-related commands is via the File >
Utilities option. From version 8.0 onwards,
the tool menu includes a separate Structure
Tools menu. This article refers only to the later
version of the interface.
43
Generating a conversion table
A conversion table document is a normal
FrameMaker document. The conversion table
itself contains three columns. The first column
lists the objects on the body pages with a
prefixed object tag.
Supported object tags are as follows:
P
C
T
TT
TH
TB
TR
TC
Paragraph
Text range
Table
Table title
Table heading
Table body
Table row
Table cell
SV System variable
UV User variable
G Graphic
M Marker
X Cross-reference
TI Text insert
Q Equation
F Footnote
The second column lists the element within
which each object will be wrapped. The third
column is used to list any labels that may be
used to identify the element in EDD rules. These
labels are known as qualifiers and are used
to apply rules to an element based on some
specified condition, such as the position of
the element in the structure hierarchy. Typical
uses of qualifiers include applying specific
formatting to heading elements of varying
levels. We discuss qualifiers further in the
section Modifying the conversion table.
You can create a conversion table manually
if you wish, but you will find it quicker to
let FrameMaker generate a table for you.
The procedure for automatic generation of a
conversion table is as follows:
1. Open FrameMaker.
2. Open the document to be structured.
3. Select Structure Tools > Generate
Conversion Table > Generate New
Conversion Table > Generate.
FrameMaker runs over the body pages of the
document and builds a list of all the objects
that can be structured. It assigns an object
tag to each object and maps each object to an
element.
Running the Generate command on our
sample document produces the conversion table
shown in Figure 4.
Modifying the conversion table
Modifying the conversion table generally
(although not exclusively) involves performing
four types of modification: renaming elements,
adding qualifiers, defining a root element and
nesting elements.
Renaming elements: You may have noticed
that the automatically generated table contains
elements that are not are defined in the EDD.
A glance at the table in Figure 4 reveals that
Body, Heading1 and Heading2 are listed as
elements in the second column.
Before you can apply the conversion table
to your document, you need to replace these
elements with others that are actually contained
in your EDD.
Here is where familiarity with your intended
Figure 4. Sample initial conversion table
Figure 5. Conversion table with modified element entries
Figure 6. Conversion table with qualifiers added
Figure 7. Conversion table with root element defined
Figure 8. Conversion table with nested element sequences added
structure can help you quickly identify that
instances of the Body paragraph format
should be wrapped in the Para element, and all
headings (either Heading1 or Heading2) should
be mapped to the Heading element.
We can leave the ChapterTitle paragraph
format mapped to the ChapterTitle element,
since our EDD includes such an element.
Our conversion table now appears as shown
in Figure 5.
Adding qualifiers: We now need to apply a finergrained distinction to the Heading element so
that we can differentiate between the Heading1
and Heading2 paragraph formats in our output.
We do this by adding a label to each paragraph
format in the third column of the conversion
table. This label is known as a qualifier.
44 Tools
Qualifiers
enable you to tell
FrameMaker how to
process an element
when you need
to map several
paragraph formats
to the same element.
This is often the
case when mapping
headings of varying
levels to a generic
Heading element,
or when mapping
items in bulleted and
numbered lists to a
generic Item element.
There are some
restrictions on the
Figure 9. Stucture added to sample document
characters that can
be used in a qualifier,
but the regular
alphanumeric characters are all valid. Do note,
however, that qualifiers are case-sensitive. In
our example, we will use Head1 and Head2 as
qualifiers.
Our conversion table now appears as shown
in Figure 6.
Defining a root element: From FrameMaker
version 7.2 onwards you can specify the
highest valid element of your structure in your
conversion table. This element is referred to
as the root element. In our example, the Parent
element is defined as the highest valid element,
as shown by the text Valid as the highest-level
element in the EDD at Figure 2. The diagram in
Figure 3 also shows the Parent element at the
top of the structure hierarchy.
To include the root element in the conversion
table, add a new first row to your table and enter
the string RE:RootElement in the first column.
RE is the object tag for the root element, and
RootElement is the object type. Then type
Parent in the second column. Our conversion
table now appears as shown in Figure 7.
Nesting elements: Although the conversion
table as it stands will wrap all document objects
in an element specified in the EDD, it does not
yet take account of nested element sequences
allowed by rules in the EDD. Nested elements
are elements which are themselves wrapped by
other elements. For example, in our structure,
a Heading element is wrapped inside a Section
element, while the Section element is itself
wrapped in a Parent element.
The conversion table needs to represent this
Parent > Section > Heading nested sequence,
as well as all other possible nested sequences.
Once again, familiarity with your structure can
help you easily identify the required sequences.
Figure 10.
The diagram in Figure 3 illustrates how our
Structure view of
EDD
contains a rule specifying that a sequence
sample document
of a ChapterTitle element followed by a
mandatory Para element is wrapped in a Prelim
element. We account for this in the conversion
table by including a row that contains the string
E:ChapterTitle, E:Para+ in the first column
(where E is the object tag for an element) and
Prelim in the second.
Similarly, the EDD states that a Heading > Para
sequence, or a Heading > Para > Section sequence
must be wrapped in a higher-level Section element.
This rule is true for both the Heading1 and
Heading2 paragraph styles, as specified by our
earlier use of the Head1 and Head2 qualifiers in
Figure 6.
The conversion table thus requires
one additional row with the string
E:Heading[Head1], E:Para+, E:Section* in the
first column, and a further additional row with
E:Heading[Head2], E:Para+, E:Section* in the
first column. In both cases, Section should
appear in the second column.
The conversion table now appears as shown
in Figure 8.
Applying a conversion table
The next step is to apply the conversion table to
the target document. You do this as follows:
1. Open the document to be structured and the
document containing the conversion table.
2. Select Structure Tools > Utilities > Structure
Current Document.
3. From the Conversion Table Document
drop-down list, select the document
containing the conversion table.
4. Click Add Structure.
FrameMaker applies the structure defined by
the conversion table to the document. In our
example, the result is shown in Figure 9.
Note that the formatting for Heading1 and
Heading2 is identical at this stage.
The corresponding structure view is shown in
Figure 10.
To apply the correct formatting to the
Heading2 paragraph format, we must now
import element definitions from the EDD.
Figure 11. EDD imported into sample document
45
Importing element definitions
This step is similar to the previous one.
1. Open the document to be structured and
your EDD.
2. Select File > Import > Element Definitions.
3. From the Import from Document dropdown list, select the document containing
your EDD.
4. Click Import.
FrameMaker applies the element definition
rules defined in the EDD to the document. In
our example, the result is shown in Figure 11
where we see that the correct formatting (black
colour and smaller font than Heading1) is now
applied to the Heading2 paragraph formats on
the left towards the bottom of the graphic.
The change to the formatting has no effect on
the structure view shown at Figure 10.
Troubleshooting tips
Inevitably, in real-life working environments
your structure will be more complicated than
in our simple example, and your EDD will
contain many more elements than are used
here, especially if you are using a restricted text
sample to begin with.
Consequently, it is possible that the initial
conversion table generated by FrameMaker will
lack some of the elements in your EDD, and
that you will need to add these to your table
manually.
By extension, it is probable that many of the
nested element sequences allowed for by your
EDD will also be missing, and that these too will
need to be added manually to the conversion
table with appropriate use of qualifiers.
The more complicated the defined structure
you are implementing, and the weaker your
familiarity with it, the more iterations of this
manual modification process you are likely to
need.
Test and fix your conversion table rules
on a representative sample of the text to be
processed by the table. Include in the sample
all the objects you expect your documents to
contain.
As a rule of thumb, it is recommended that
you populate the first rows of your conversion
table with rules that wrap individual document
elements. Follow these with rules that wrap the
basic child elements inside a parent, then with
rules that wrap elements into sequences. The
last rules in the table should be those wrapping
elements in the highest-level element. In this
way, you will create a useful visual
representation of how conversion table
processing is performed from the lowest level
up, which can help you with your rule-writing. C
Andy Lewis is a
long-time user
of FrameMaker
and its plug-ins in
both structured
and unstructured
environments. He has
presented and written
extensively about his
experiences. He has
recently joined the WAS
Content Development
team at Verint Systems
in Herzlia, Israel where
he is scaring his new
colleagues with his
plug-in freakishness.
E: andylewis0@gmail.
com
W: www.verint.com
www.linkedin.com/
in/andylewis2003
Cologne, Germany
Localization Certification Program: September 6–8, 2010
Localization Project Management Certification: September 9–10, 2010
Gain cutting edge localization skills and training to facilitate your career
progressioninthefieldsoflocalizationandinternationale-business.
Learn from industry leaders and expand
Who Should Attend?
yournetworkofcolleagues.
Translators
Three Steps to Certification:
Project managers
Self-paced,online instruction
Localization professionals
Intensive, hands-on workshop
Marketing professionals
Certificationexam
Professors & students
Web developers & designers
International&e-businessprofessionals
September 6–10, 2010
Register Today: rce.csuchico.edu/localize
46 Editing
Using the active and passive voices
We’re often told to write in the active voice. Jean Rollinson considers
when this is good advice and when it may be questionable.
One of the first things I was told as
a trainee technical author was that
I should write in the active not the
passive voice. As an engineering
graduate who attended school
in the 70s and 80s, when formal
grammar lessons had been abolished,
I had no idea what my boss meant.
However, some research and 16 years
as a technical author have taught
me much, including the difference
between the active and passive
voices, and how to change one to
the other.
You should note that it is not always
correct or appropriate to use the active
voice in technical writing. There are
occasions when you need to use the
passive voice for the text to be easily
understood: it is part of your job as a
technical communicator to know when
to use each voice.
Active voice
When you use the active voice, the doer
is given importance over the action.
Thus, you should use the active voice
when the doer is important. The active
voice tends to make your writing clear,
direct and strong because it uses
active verbs, so you should use it for
instructions.
Examples of the active voice are:
I add milk to the mixture.
The garden designer tried different
plants.
I will not carry out any research in
this area.
The teachers have marked the work.
The builders are repairing the hole in
the roof.
You must turn off the lights when
you leave the building.
He decided to mend the gate.
She suggested using a plain
background for the presentation
slides.
Passive voice
When you use the passive voice,
the action is given prominence over
the doer. In general, you should use
the passive voice in writing such as
reports, proposals and letters, because
the action not the doer requires
emphasis. You may also find that you
want to use the passive voice to avoid
explicitly apportioning blame. For
example, ‘100 of the widgets received
by us did not work’ may be better than
‘your company sent 100 widgets that
did not work’.
Examples of the passive voice are:
Milk is added to the mixture.
Different plants were tried by the
garden designer.
No research will be carried out in this
area by me.
The work has been marked by the
teachers.
The hole in the roof is being repaired
by the builders.
The lights must be turned off when
you leave the building.
He decided that the gate should be
mended.
She suggested that a plain
background should be used for the
presentation slides.
Changing active to passive
In general, you can do this using the
following steps:
1. Identify the subject of the sentence,
that is, what is causing the action.
2. Identify the object of the sentence,
that is, the thing that has been
acted upon.
3. Note the tense of the verb.
4. Rearrange the sentence so that it
begins with the action.
5. Use the third person form of the
verb preceded by the appropriate
auxiliary verb and followed by the
phrase ‘by the’.
6. Add the subject of the active
sentence, to complete the passive
sentence. Note that sometimes this
may be implicit and can be left out.
You can see examples of this change
by comparing the active and passive
sentences in the previous sections.
Note: Not all sentences can be
transformed from active to passive,
only those that use transitive verbs
(verbs that take objects). Sentences to
watch for are those containing certain
verbs such as have, lack, resemble,
contain, suit and fit. Perhaps the most
important of these is have. For example
you can say ‘He had a car’ but not
‘A car was had by him’.
Changing passive to active
This is what you are more likely to
have to do in technical writing, as many
people seem instinctively to write in
the passive voice even when the active
voice would be more appropriate.
In general, you can do it using the
following steps:
1. Identify what is causing the action,
often what followed ‘by the’ in the
passive sentence. If this is implicit
in the passive sentence, then you
need to infer it from the action or
context.
2. Identify the action performed
(usually at the beginning of the
passive sentence).
3. Note the tense of the verb.
4. Rearrange the sentence so it begins
with the doer.
5. Choose the appropriate form of the
verb.
You can see examples of this change
by comparing the active and passive
sentences in the previous sections.
Conclusion
You can use both active and passive
voices in formal writing. To decide
which to use, you need to know where
the focus of the sentence needs to be.
Using only the active voice can result in
stilted prose, but using the passive
voice inappropriately can make your
writing verbose and complicated. C
Further reading
A Dictionary of Modern English Usage
H W Fowler, Wordsworth Editions
Oxford Style Manual, Michael Ritter,
Oxford University Press
Practical English Usage, Michael Swan,
Oxford University Press
Technical Communication: English Skills
for Engineers, Meenakshi Raman
and Sangeeta Sharma, OUP India
Jean Rollinson FISTC is 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 concert band.
W: www.authoring-services.co.uk
47
Book review
Five Steps to MadCap Flare
By Lorraine Kupka and Joy Underhill
ISBN-13: 978-1-934229-10-1, soft cover, 380 pages, $49.95, WME Books Rochester NY USA (April 2009). Reviewed by Ed Clayton MISTC
MadCap Flare will be a familiar
product to those who have attended
industry gatherings, such as the ISTC’s
Technical Communication UK, or to
readers of Matthew Ellison’s reviews
of various versions of the product for
Communicator. Suffice to say here
that Flare can be used to create help
systems, knowledge bases and printed
documentation, in principle from the
same set of topic files.
Flare is shipped with a full online
help system, and many hundreds of
pages of documentation describing,
for example, the procedures for moving
content from Adobe FrameMaker and
Microsoft Word. The basic question
then, is whether Five Steps to MadCap
Flare adds to what is already provided
by MadCap Software.
At around the same time that I
volunteered to write a review of this
book, a message was posted on the
ISTC forum, asking for opinions on
Flare. The responses revealed that a
number of people found the product
difficult to learn and not intuitive.
The book deals with Flare at version
4.2. Flare 6.0 has recently been
released; I have contacted the authors,
and the book is undergoing revisions to
bring it up to the latest version.
In this review, I won’t describe
each chapter in the book, as this
is comprehensively dealt with by
Nita Beck and Ginny Reynolds, in
their own review, which is available
from www.wmebooks.com/
Five_Steps_to_MadCap_Flare_by_
Kupka_Underhill_p/1934229105.htm
Five Steps to MadCap Flare aims
to be comprehensive and, to achieve
this within a fairly slim volume, the
authors refer the reader to a range of
resources, such as Flare’s own online
help system, the PDF documentation
that is available with Flare and
the MadCap knowledge base. This
approach works well. The book feels
comprehensive in its scope, without
getting bogged down in detail that
is perfectly adequately provided by
MadCap’s own resources.
The book develops logically,
starting with a chapter covering the
principles of topic-based authoring
and explaining aspects of Flare’s
terminology. Further chapters explore
Flare’s interface and the intricacies of
the XML editor.
The authors emphasise the need for
careful planning and to assist with
this, the book contains a selection of
planning worksheets. These can be
photocopied and used to identify, for
example, all the intended outputs for
a Flare project, the names of condition
tags, and the names of the master
pages, master table of contents, page
layouts and targets.
The book also provides a number
of step-by-step tutorials. There is
a particularly useful one on setting
up page layouts for print output, a
procedure that MadCap themselves
acknowledge can be tricky (the
company recorded a seminar on this
subject). A number of appendices
provide valuable reference information
on the XML editor and troubleshooting
problems with Flare and there are
useful sections on single sourcing and
providing context-sensitive help.
Flare is a substantial product, and
I don’t envy the task of the authors in
deciding what to include and exclude,
given that they have targeted both
new and experienced users. On the
whole, the book is successful in its
aims but I have some quibbles over the
broadness of the approach.
I would expect Flare to be considered
by technical communicators tasked
with the creation of long documents
or help systems, who currently use
other products, such as Microsoft
Word, Adobe FrameMaker and Adobe
RoboHelp.
Yet the book states that it ‘addresses
the needs of new Flare users who
have little experience with document
authoring tools’. To this end, some
content is included that is not
necessary for what I would judge to
be its target audience. For example,
the book weighs up the value of using
paragraph and table styles, as against
the direct application of formatting.
I think most readers will be familiar
with such issues and, in this instance,
I would have preferred the book’s
focus to be a little narrower.
In addition, the book tries to cater
for various versions of Flare, and
to explain some of the differences
between pre- and post-4.0 versions.
This makes some examples longer and
more convoluted than they need be.
I believe that, despite the
comprehensive documentation
supplied with Flare, there remains
scope for independently produced
books on Flare, such as this one.
Notwithstanding some criticisms of
what the authors have decided to
include, I regard the book as very
welcome and valuable for new or
potential users of Flare, and I look
forward to the updated version. My
hope is that the revised version will
contain even more in the way of hints,
tips and advice on best practice. C
The authors are updating their book
for Flare version 6. Lorraine writes,
‘We are including information about
newer Flare features, we’re revising
the existing topics and we’re updating
our recommendations for new users.’
The new edition will be available
later this year. We will publish a review
in a future issue of InfoPlus+.
bout the book’s authors
A
Lorraine Kupka has 16 years’ experience
writing documentation for end users and
software developers. She has written about
such diverse topics as airport baggage
screening, cardiac catheterisation systems,
worldwide shipping and law enforcement.
Joy Underhill has written for Fortune
50 businesses for more than 25 years. In
addition to her extensive technical writing
background, Joy specialises in marketing
communications, web copy development
and article writing.
48 Ethical dilemmas
Truthtelling in customer communications
Warren Singer launches a new series that invites your thoughts on
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. This series will present
examples of real-life problems faced by
technical communicators at work. What
would you do in their situation? After
reading each story, let us know how
you would solve the dilemma. The best
responses will be published in the next
issue of Communicator.
This quarter’s dilemma
Note: All names and places have been
fictionalised to protect the identities
(and reputations) of real people.
The background
Jane had been working as a technical
communicator for a number of years
for a large, multi-national bank.
She was comfortable at her job and
respected by her colleagues.
The culture in the bank was highly
conformist. Speaking out or taking the
initiative was strictly frowned upon. All
projects had to go through the necessary
processes and channels. The bank also
had an implicit ethos that aggressively
targeted big business and opportunities
for market expansion, often at the
expense of smaller businesses or
individuals. Although Jane had her
concerns about this ethos, she had coped
up to now in this environment; her
job role was quite straightforward and
primarily involved reviewing and editing
technical user guides intended for users
of one of the bank’s online systems.
The project
That year, the bank embarked on an
ambitious technical migration of one
of its key systems. Business customers
currently on one platform would all be
migrated to a new platform, which was
an adaptation of a platform that the bank
had recently acquired. The merging of
the two business platforms would bring
significant cost-savings to the bank.
Jane, as the senior technical
communicator in this part of the bank,
was charged with putting together
the communications programme
and support documentation for the
customers who would be migrated.
This included producing e‑mail
communications that explained the
reasons for the change and when it
would be made, as well as the features
and functionality of the new system.
Jane was told that the migration
would be pitched to small business
users as an ‘upgrade’ (larger companies
would be discreetly informed by
their account managers that this was
actually a migration).
It quickly became apparent to
Jane that the new system lacked
fundamental features and would
cause difficulties for many smaller
customers. It had been designed
primarily for large corporate
customers, which the bank was clearly
interested in acquiring, but was not so
suitable for small businesses. However,
the prevailing attitude among senior
managers was that small businesses
were not important; they did not bring
in significant amounts of revenue and
the bank was happy to lose customers
at the lower end of its customer base.
To help with the platform migration,
dedicated account managers had
been assigned to the large corporate
customers that were of real value to
the bank. In some cases, compensation
was being offered to help corporate
customers migrate to the new system.
No funds or dedicated support were
available for smaller businesses.
The migration project had faced
severe challenges. Tens of millions
of pounds had been poured into
a seemingly bottomless pit as the
project, already two years behind
schedule, struggled to stay on course.
Many of the features that had been in
the blueprints to help small businesses
Notes on the dilemma
Technical communicators are often
expected to bring a marketing or PR
perspective to their technical work. The
selective filtering of information can lead
to potential ethical problems. Often, an
author may feel pressured to limit what
the reader ‘needs’ to know in order to
present the organisation’s perspective.
were now starting to fall by the
wayside in an effort to cut costs.
Jane’s dilemma
Jane’s dilemma was that senior
managers wanted plenty of positive
‘spin’ on the new system. They wanted
to up-sell the benefits and gloss over
the missing features. They wanted to
promote some features, while putting
inconvenient aspects in the technical
details where they would be more likely
to pass unnoticed.
For Jane, this presented an ethical
dilemma. As a technical communicator,
she felt responsible for the wording she
chose to communicate with customers
and for communicating clearly with her
target audience. To her, it did not seem
fair on the smaller customers, who
deserved to know what the implications
for their businesses would be.
Although the bank was not being
directly untruthful, it was being
selective in the way in which it wanted
to present information to its small
business customers. In particular,
using terminology such as ‘upgrade’
implied a different thing from
‘migration’. It was understandable that
the bank would want to portray the
migration in a positive light but was its
approach the right thing to do? Could
it not backfire on the bank in the long
term, not only by losing customers but
also by giving it a bad reputation in the
small business community?
Jane discussed the issue with her
project manager, who told her: ‘I
understand what you’re saying, but
this has already been agreed. We
can’t change this now. If customers
don’t like it, they are free to take their
business elsewhere.’
What should Jane do? It was unlikely
that she would be able to influence
the decisions being made by senior
managers. Also, given the culture of
conformity, speaking out would at best
be frowned upon and, at worst, brand
her as a rebel. Senior managers did not
take kindly to people talking about or
challenging them on their plans.
On the other hand, did she not need to
consider her professional integrity and
responsibility towards her customers? 
49
International standards
A standard for simplified natural language
ISO is developing a new standard to address Simplified English.
Richard Hodgkinson reports on the opportunities for involvement.
In my article in the Spring 2010
Communicator, I reported on a
proposal for a new international
standard that would address Simplified
English. The proposal has now been
accepted and development of multipart
standard ISO 24620 is now underway
in ISO/TC 37/SC 4/WG 5 — Terminology
and other language and content
resources — Language resource
management — Workflow of language
resource management. UK participation
in this standard is being managed by
British Standards Institution committee
TS/1 (Terminology).
I will not be participating directly
in this project, but will report on its
progress in Communicator.
So, what’s it all about?
To provide more information on the
purpose and intended content of this
standard, I am including here the
Introduction and Scope from an early
Working Draft. As the project is in its
initial stages, these sections may be
modified as the standard progresses.
If you’d like to participate in the
project by reviewing drafts and
providing content and comments,
contact Beverley Webb, the TS/1
secretary, at [email protected].
com. You will need to provide a
nomination from the ISTC together
with a brief biography. C
Richard Hodgkinson FISTC has
participated in the development of ISO,
ISO/IEC and European standards addressing
icons, symbols, software documentation,
pen gestures and ICT accessibility since
1990. He is also an Associate Lecturer on
the MA Technical Communication course at
the University of Portsmouth.
Introduction
The volume of technical documentation and other kinds of special purpose language
(SPL) texts is increasing in the course of an ever growing number of products
and services to be described in sometimes many different languages for experts,
experienced users or general users being potential users of these products and
services. Therefore, translation, localization and other approaches– not to mention
automatic translation of different sorts — use computerized methods to accelerate
the time to market, while at the same time improving the quality of texts and their
consistency across different language versions. On the one hand readability and
understandability are key factors of user-friendliness and, therefore, decisive in market
penetration. On the other hand, the quality of the original text and that of its different
language versions may become subject to liability.
Natural language permits a great amount of expressive variation. Writers, especially
technical writers, tend to develop their special vocabularies and jargons, styles, and
grammatical constructions. Thus technical language can become opaque not just to
ordinary readers, but to experts as well. The problem becomes particularly acute when
such text is translated into other languages, since the translator may not even be an
expert in the technical domain.
To counter the tendency of writers to use unusual or overly-specialized, inconsistent
language, simplified language approaches have been developed, which also cover
some aspects of controlled languages (CL). Simplified language approaches started
off from simplified English, which was developed by the aerospace industry and
its customers to help the preparation of maintenance manuals that are both clear
and unambiguous for English speakers and non-native English speakers alike. The
specification provides a set of writing rules and a dictionary of agreed words with their
meanings. Today these approaches are applied also to other languages, while at the
same time computer-assisted approaches in this field increasingly need to become
interoperable and the resulting texts in several or many language versions to become
re-usable for an array of complementary uses.
This situation calls for language independent general rules and principles, which
may have to be complemented by language dependent rules and principles as
well as the necessary language and content resources. This International Standard
responds to the needs of multilingual approaches in translation and localization of
technical documentation and, therefore, focuses on the general rules and principles of
simplified natural language(s).
Scope
General rules and principles concerning simplified natural languages facilitate:
Reducing ambiguity;
Speeding up reading;
Improving comprehension for people whose first language is not the language of
the document at hand;
Improving comprehension for people with different domain or application background;
Human translation and localization to become easier, faster and more cost effective;
Computer-assisted translation and machine translation.
Re-usability of language resources in larger application scenarios, like Semantic Web
or decision-support systems;
The general rules and principles of this standard constitute a systematic approach
that makes cross-language and cross-domain as well cross-system applications of
simplified natural languages more effective.
Over to you
Write to [email protected]
Tell us how you think Jane should solve her ethical dilemma. The next issue of
Communicator will feature your responses. If you have a dilemma you’d like advice
about, write to us in confidence. If we think your issue will interest a wider audience,
we’ll air it here (don’t worry — we’ll protect your anonymity!).
Warren Singer MISTC
50 A day in the life
Colum McAndrew
describes a typical
working day in the
period after finishing one
major project and before
starting the next.
‘My name is Colum and I’m a
newsaholic!’ My working day starts
with the radio alarm and the reassuring
sound of James Naughtie, John
Humphries or Euan Davis on the Today
programme. It gives me just the right
mix of news, politics, sport and current
affairs (in that order of importance)
to start the day. Down to the kitchen
for a glass of fresh orange juice, a
habit I picked up while living in Florida
for a month, and then back up to the
bathroom.
During a breakfast of Branflakes,
banana and a cup of Assam tea (made
with real tea — no tea bags allowed
in the McAndrew household), I read
Private Eye while keeping an ear out
for anything interesting on the radio.
Breakfast over, I drop my wife off at
the station before heading to Guildford
with the aforementioned radio
presenters for company. If the traffic
behaves itself, the journey takes 45
minutes; when the school’s are out, it’s
more like 30.
Once at my desk, I start with a pintglass of water. After a few gulps, it is
time for e-mails. This means adding
items to my ‘to-do’ list and hopefully
delegating some to others in the
team. As a long-time user of Adobe
RoboHelp, my day also starts with
monitoring the forums’ RSS feeds and
scanning Twitter for interesting tweets.
I am fortunate to have an employer
that recognises the need for personal
and professional development,
so spending 15–30 minutes a day
answering queries is time well spent
and immensely satisfying.
Among today’s actions is one to
complete a Q&A session for the blog
of Adobe’s Senior Product Evangelist,
RJ Jacquez. Apparently, a recent
blog post of mine on how our use of
RoboHelp Server helped improve our
documentation interested him. This
is the latest in a list of collaborative
efforts we have had with Adobe,
the most recent being a Use Case
Study on our use of the Technical
Communication Suite.
Mid-morning, a member of our Help
Desk contacts me with a productrelated query. Our teams work closely
together as they review our work.
The Help Desk gets direct customer
feedback so that team’s review
comments help us to ensure our
documentation includes the required
detail. The problem comes when
they expect me to remember what I
wrote over 18 months ago! We end
up opening the help file and looking
together. He could have done that but
at least it proved the help worked and
hopefully he’ll try that first next time.
Having recently completed a major
rewrite, a lot of my time is currently
spent on smaller projects, while
looking strategically ahead. Our team
meets bi-weekly and it is normally
down to me to find items we need to
discuss and agree a way forward. It is
also a useful opportunity to provide
training to other team members.
I normally manage to escape for
lunch. Working in a remote location
means there isn’t a lot to do nearby but
it does make for good running routes.
If my ageing knees allow it, a 40-minute
run around the fields and parks
nearby, rather perversely, never fails
to relax me. After showering, I return
to my desk for a sandwich, fruit, yet
more water and whatever the afternoon
throws at me.
Thankfully, my days are not too full
of meetings. Today I have just one, a
Release Board, which lasts only ten
minutes. We agree to release. Hurrah! In
the afternoon, an impromptu meeting
with my boss brings her up to speed
with the goalposts that have moved
during her absence from the office.
As the working day nears conclusion,
inane topics of conversation abound
around the office. The pros and cons of
a new religious model, heated settees,
a taxi service for both you and your
car, and how my colleague is going
to prevent his 11- and 9-year-old
daughters from having any boyfriends
until they’re 30!
In the car going home it is more
Radio 4 news and, depending on the
time, the comedy half-hour. Once home
I can relax, unless my in-laws have
other ideas. The film My Big Fat Greek
Wedding has to be one of the most
astute, accurate and witty portrayals of
marrying into a Mediterranean family
and should be compulsive viewing for
anyone thinking of taking the plunge.
As in the film, my in-laws have very
healthy appetites and are lively, fun
and loud. Oh, and quite a few of them
live nearby!
At some point in the evening,
normally after ringing my mother to
make sure she’s OK, I retire to my
oasis of calm, my study, complete
with another Assam tea. I do voluntary
work for Amnesty International so
there are inevitably e-mails to send,
phone calls to make and, if it is close
to a Board or Sub-Committee meeting,
a hefty pile of documents to read. If
I have the inclination, I’ll write a post
for my RoboColum(n) blog and check
the RoboHelp product forums one last
time. The aim is to complete these by
10pm so that I can end the day where
I started, catching the BBC news and
weather.
Fully conversant with world events,
I’m off to bed where I fall asleep
instantly, much to my wife’s
annoyance. As someone who has
difficulty getting to sleep, she often
wants to talk instead. Strangely, for a
professional communicator, 11:30pm
after a busy day is not my most
productive time! C
translation
localisation
authoring
illustration
publishing
Entering new markets? Go native.
When it comes to software localisation, Imprimatur delivers a complete solution that
encompasses help and support systems, documentation and manuals, and marketing
and sales support materials - as well as the application user interface.
We begin with detailed analysis of both the source materials and your target markets,
and then we incorporate cultural, social and linguistic considerations into our
translations to produce materials that integrate into your destination markets as if you
had created them there in the first place.
Contact us to discover how we can help you.
Imprimatur Limited
22 Church Street, Godalming
Surrey GU7 1EW, England
Tel: 01483 791400
Email: [email protected]
www.imprimatur.co.uk

Communicator Summer 2010.indd

Transcription

Similar documents

P9S and VP70Z HK P2Al and Emergency Flare Launcher

David Pogue`s missing manuals

Minding your language Setting procedures in stone

Cut away, explode or animate?

laundry room transformation

Power Pick Global Communicator Pro

UltraVu® II 5330

Star Mall convert

Madcap Conv head.indd - MadCap Racing Engines

Stock Speed Covers - Highland Supply Corporation