David Pogue`s missing manuals

Transcription

Communicator
The Institute of Scientific and Technical Communicators
Summer 2006
Getting to grips with
MadCap Flare 1.0.2
Seeking ways to
work more flexibly
Framing your skills for
the information age
Designing dynamic toolchains
for fast-moving products
David Pogue’s missing manuals
Meet the creator of this best-selling series
Great Expectations?
If you have high hopes for high
standards of translation, make the leap
to ITR and discover why top quality
needn’t cost you more!
Key features of our translation
services include:
• Translation of all types of
documentation from marketing
collateral to technical manuals
• Expertise with all major DTP tools
including single-sourcing for multiple
output formats
• Localisation of software, online help,
and corporate websites
To find out more about how your
company can enjoy all the benefits of
ITR’s services, please contact
ITR International
Translation
Resources Ltd
1 Dolphin Square
Edensor Road
London W4 2ST
Tel: 020 8987 8000
Fax: 020 8987 8008
Web: www.itr.co.uk
Email: sales@itr.co.uk
• All major languages including Arabic,
Chinese, Japanese, Korean and
Russian
• Scaleable teams of domain specialists
ready to meet the requirements of
any size of translation project
• Terminology management to achieve
technical accuracy and consistency
from project to project
• High-performance leveraging from
customised translation memories to
help reduce your translation costs on
an on-going basis
• Comprehensive linguistic quality
assurance processes designed to
optimise the success of your
translations in market
• Integration with your publishing
environment and workflow processes
for painless file transfer.
Contents
10
Communicator The quarterly journal of the ISTC
ISSN 0953-3699
Production team
Editor
Questioning the relevance of this rule of thumb to information design
13
16
News editor
Amanda Bates
Skills Framework for the Information Age
Ron McLaren
Standardising the definition of technical communication skills in IT
Kathryn Valdal Fourie, newsdesk@istc.org.uk
Copyeditors
Tony Eyre and Nick Robson
18
Tim Joynson and Linda Robins
Layout
22
Newell-Porter Limited, www.newellporter.co.uk
Advertising
Felicity Davie, felicity@tou-can.co.uk
or 01344 466600
Carol Hewitt, istc@istc.org.uk or 01733 390141
Submissions
Guidelines
Review of MadCap Flare version 1.0.2
Carol Johnston
Finding out what the latest authoring tool offers for Help designers
26
David Pogue and the missing manuals
Linda Robins and Richard Truscott
Investigating the best-selling series and the man behind it
Subscriptions
30
Googling more effectively
Paul Beverley
Getting the most out of this popular search engine
www.istc.org.uk/pages/journals.php
copy by
published
copy by
published
copy by
published
copy by
published
User training with OnDemand
Dirk Manuel
Profiling a project that used this tool to create global training exercises
Proofreaders
Spring
Summer
Autumn
Winter
Adjusting the balance
Exploring the role of flexible working practices in work-life balance
Marian Newell, journal.editor@istc.org.uk
or 01344 626895
Deadlines
The magical number: seven ± two
Matthew Ellison
31 January
21 March
30 April
21 June
31 July
21 September
31 October
21 December
32
Providing up-to-date information for fast-moving software products
36
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)
Carol Hewitt, ISTC Administrator
PO Box 522, Peterborough, PE2 5WX
T: +44 (0) 1733 390141
F: +44 (0) 1733 390126
E: istc@istc.org.uk
W: www.istc.org.uk
Bombproof your CV!
Dave Cooper
Keeping your details pristine during their journey to the recruiter
39
Back issues
www.istc.org.uk/pages/members/commun.php
(ISTC members only)
Soft documentation
Thomas Guest
Mastering master pages: part 1 of 2
Steve Rickaby
Controlling the layout of your FrameMaker document’s pages
42
Affiliate and industry news
Kathryn Valdal Fourie
44
Bill Johncocks
46
Society for Editors and Proofreaders
47
48
49
50
Indexing
Editing
Illustration
Bettina Giemsa
International standards
Richard Hodgkinson
Translation
Susan Eustace
Member profile
Poornima Kirloskar-Saini
cover Photograph courtesy of David Pogue, best-selling author and
the man behind the missing manuals series (pages 26-29)
Communicator Summer 2006
ISTC news
Article writing: tip #1
along with suggestions I’ve heard from
readers and peer reviewers.
Let’s start at the beginning: how do
you open your article? The two most
common mistakes I see are missing
introductions and boring introductions.
As in a technical document, you need
to tell your readers what your article is
about. However, unlike in a technical
document, you also need to make them
want to read it.
Ron Blicq’s article on applying
dramatic principles to your writing is a
good place to start (pages 10–12,
Autumn 2005, Communicator). Then
take a look at some popular magazines.
You’ll find most articles start with
some kind of hook, sometimes on a
topical theme, and the writer will often
return to this in some way at the end.
The circular technique provides some
kind of conclusion, or resolution, to the
piece. It reminds you where you started
and, hopefully, demonstrates how
much you’ve discovered since then. C
In coming editorials, I’ll be passing on
brief tips for making your articles more
interesting to readers. These will reflect
the experience I’ve gained as Editor and
my reading of the wider writing press,
Marian Newell FISTC
E: journal.editor@istc.org.uk
skills frameworks and bombproof CVs.
I’d especially like to thank Linda Robins
and Richard Truscott for responding to
my request for members willing to write
about David Pogue’s missing manuals
series. They have produced a thorough
analysis of the factors that contributed
to this publishing success story.
Crystal-ball gazers?
I plan to carry a series of speculative
articles, looking at our professional
future from all angles. Please contact
me if you can write about trends in:
 Tools or delivery formats
 Use of external service providers
 Off-shoring of content creation
 Legislative and regulatory changes
 Recruitment.
Some of the ISTC’s Business Affiliates
in particular may be interested in this
opportunity to write more broadly about
where we’re going and how we get there.
Editorial
In this issue
We have a great variety of articles
this time, which I hope you’ll enjoy.
Particularly timely is the review of
MadCap’s new Flare Help authoring
tool from Carol Johnston of Cherryleaf.
Always relevant are career-related
articles, this time on flexible working,
Stand out from the crowd
with an ISTC award
Do you design clear, concise and effective information? Of course
you do! So why not submit an example of your best work for the
ISTC’s 2006 Documentation Awards?
It’s a chance to see how you measure up to your peers. If
you win, you will be presented with your award in front of
an audience of technical communicators and publication
managers at the ISTC Conference. Your name, and your
company’s name, will be publicised in the ISTC’s journal,
Communicator, as well as in the newsletter and in press
releases to the media at large.
In a competitive world, winning an award could put you at
the head of the queue for future contracts or jobs.
CLASS 1
PRINTED DELIVERY
Class 1a Technical Information
(sponsored by AST
Author Services Technical)
Class 1b Non-technical
Information
(sponsored by
TechScribe)
CLASS 2
ONLINE DELIVERY
Class 2a Technical Information
(sponsored by AST
Author Services Technical)
Class 2b Non-technical
Information
(sponsored by
Plain Words)
•
•
•
•
•
•
Entries must be written in English.
Entries must have been issued between April 2005 and July 2006.
ISTC membership is not required.
Winners will be notified in September 2006.
Awards will be presented at the ISTC Conference in October 2006.
Closing date for entries is 1 August 2006.
For more information, visit
www.istc.org.uk/pages/awards.php
or e-mail awards@istc.org.uk
Letters
Students’ writes
Malcolm Beaumont MISTC
I’ve recently been a stop-gap lecturer
at a university. While marking
assignments, I’ve noticed two themes
in the work of most students. First,
they are unable to express their
thoughts in written English. Second,
they mindlessly lift material from the
web, offering only very superficial
attempts to integrate it effectively.
The writing deficiencies left me
wondering about cause and effect.
Theory one: school English lessons are
failing to instill basic writing skills,
leaving many university students
unable to do anything other than lift
web material. Theory two: lifting web
material is so ingrained in school
coursework that university students
didn’t use and develop writing skills
sufficiently in their earlier education.
Whatever the reasons are, most of my
student group lack the literacy skills to
benefit from a university education.
If my group is typical, it suggests a
reduction in the number of people who
can use written English adequately,
reversing the progress of the twentieth
century. This should be good news
for future generations of professional
writers. But how will these writers
obtain the required skills? Will they
learn the basics of written English on a
specialist university course?
The poor use of web material isn’t a
problem of plagiarism — the students are
asked to provide a reference list and to
cite references in their text. The problem
seems to be that, even though the web is
now firmly embedded in all education,
no one ever explains to students how
to use web material effectively. Many
students assume the search engines
can do all the work for them, including
editorial decisions on relevance and
objectivity. The outcome is that the
tools select the content, not the author.
Scientific communication:
call for contributions
Marisa Fernandez MISTC
I am researching an article for
Communicator on the subject of
‘scientific communication’. More
specifically, I am exploring the range of
occupations of those working in the field
and the work opportunities in the sector.
In order to make the article as compre
hensive and useful as I can, it would be
very helpful if I could have as many contri
butions as possible from ISTC members.
I don’t need anything elaborate — an
informal e-mail with a few ideas would be
sufficient. Any information that I receive
will be used only to help me produce the
article. I will not pass on any details to
anybody else and I will not identify or
quote anybody without their permission.
I would love to hear from those
who work or would like to work as
scientific communicators, and also
from anybody with a general interest
in the subject. Please contact me at
marisa.fdez@blueyonder.co.uk (subject
‘ISTC science’) for more details. Many
thanks in advance for your help.
• Translation of manuals
• Translation of manuals
• DTP in your Preferred Application
• DTP in your Preferred Application
• Localisation of your Software
• Localisation of your Software
• Globalisation of your Website
• Globalisation of your Website
History of the PTI, TPA, ITPP or ISTC:
call for information
Emma Bayne MISTC
As you may have heard, efforts are
being made to produce a history of
the ISTC, covering everything from the
start (as the Presentation of Technical
Information, PTI, Group) in 1948
up until today. It will also include
the amalgamated organisations, the
Technical Publications Association
(TPA) and Institute of Technical
Publicity and Publications (ITPP).
A history of this sort requires as full
a coverage as possible, and an obvious
source is the membership — the whole
of the membership.
Do you have any old documents or
images relating to any of the abovementioned organisations? These
would be scanned and returned, not
donated. Or any anecdotes? Maybe
information relevant to the history of
the organisations?
If you have anything you think might
be remotely relevant, please feel free to
contact me in any of the following ways:
E: emma.bayne@comhem.se
P: Värdsholmsgatan 6,
151 32 Södertälje, Sweden
T: +46 (0) 8 55385459 (day-time)
or +46 (0) 73 7584949 (mobile)
We welcome letters of up to 200 words but
reserve the right to edit as required. Write
to journal.editor@istc.org.uk or PO Box 522,
Peterborough, PE2 5WX.
Using native speaking experts, our teams work with
technical authors in major corporations worldwide
to ensure that their customers get accurate and
effective messages in any discipline.
Member
ATC
CORPORATE MEMBER ITI
Association of
Translation
Companies
We're talking your language
19/19a St. Andrews Road Bedford MK40 2LL
Tel: +44(0)1234 271555 Fax: +44(0)1234 271556
www.bedfordtrans.co.uk
sales@bedfordtrans.co.uk
ISTC news
Presidential address
It’s coming up to Conference time already,
but also it’s time for the AGM. As well as
being an opportunity to catch up with
friends, meet other communicators and
learn something new, it’s also a chance to
have a say in how your Institute is being
run. The AGM will be held on the morning
of Thursday, 5 October, and you can either
come to Conference and stay for the AGM,
or just turn up for the AGM itself.
I’ve made a name for myself with
my remarkably short AGMs, because I
don’t believe in wasting everyone’s time
with unnecessary repetition. I’m afraid
that this year it won’t be as quick, but
it’s more important than ever that you
make the effort to be there.
Every year there are the usual
appointments and retirements, but this
year will be more important because
Council is proposing some major
changes to our Articles of Association.
For those who don’t know, these are
the rules by which we run the Institute
on your behalf. Having been modified
over many years to reflect changes in
working practices, many of the existing
Articles no longer made much sense.
Dr Caroline Bucklow has very kindly
worked with Council to come up with
a revised set of Articles that not only
make a lot more sense, but also fit well
with the way we actually work.
For this reason, I must urge you all to
read your AGM papers carefully when you
receive them. We honestly believe that the
changes are in the best interests of the
Institute and we hope that you feel the
same. You may not agree with us, or you
may need further explanation about some
of the changes, so read them early and let us
know. A full explanation of what changes are
being proposed and why we think they’re
a good idea will accompany the proposal,
so hopefully that’ll make it all clear.
If you can’t make it to the AGM, please
don’t think you’re excluded. Along with
your AGM papers, you’ll find a form for
proxy voting. This enables you to give
your votes to someone who you trust to
vote on your behalf, but please make sure
that they can be present and that they are
aware of your feelings on the subject.
Finally, Conference is being held from
Tuesday to Thursday. I know this has
caused concern to weekend regulars who
cannot attend, but it hasn’t been done on
a whim and is allowing people who can’t
attend on weekends to come. It won’t
necessarily be a permanent change: we’ll
see how it works and, if need be, compro
mise in future. We are listening to those of
you who prefer weekends, but also to those
who prefer weekdays. I’ll look forward to
seeing you at conference and AGM. C
Gavin Ireland FISTC
E: president@istc.org.uk
ISTC Conference - 3-5 October 2006, Gatwick
There is a better way
Keynote speaker - visual interaction designer Patrick Hofmann
Horace Hockley presentation to a well-known science broadcaster
Sessions on many aspects of technical communication - sectors, processes,
techniques, plus proposal writing, skills frameworks, internationalisation,
work environments and more
10%
early-bird
discount*
Member Rate
£345+VAT
For more information,
booking form and a full price list:
• E-mail: ann@alittlecreation.fsnet.co.uk
• Telephone: Ann Little on 020 8422 4689
• Visit: www.istc.org.uk/pages/conference2006.php
*Book before 30 June 2006
ISTC launches its new open learning course
The ISTC is now accepting applications
for its new open learning course, which
is offered in two separate parts that
can be taken independently. Students
will receive a certificate on completing
each part of the course.
Based on materials which were
purchased from John Crossley’s
estate and which have been updated
and extended by myself and Peter
Greenfield, a former ISTC President,
the course combines a proven track
record with a fresh perspective formed
through long industry experience. The
addition of case studies to the second
part will provide practical context for
the topics covered by the syllabus.
If you would like an information
booklet and application form, please
contact Carol at istc@istc.org.uk.
ISTC as an examining body
The next challenge is to organise exami
nations. We will keep you informed of
progress towards this objective, an aim
since the ISTC was formed. It is an exciting
time for the Institute and its members,
as we add an entry-level qualification to
the graduate and postgraduate degrees
available to UK technical communicators.
Courses guide
The courses shown on the ISTC website
were updated in March 2006. Thanks to
Mike Faircloth for taking on this task. If
you know of other technical communi
cation courses that should be added,
please send details to me. C
John Young FISTC
E: education@istc.org.uk
ISTC open learning course
Qualification title
Communication of Technical Information
01 Technical Communication
Techniques
02 Technical Authorship
Certificates awarded
ISTC Certificate in Technical
Communication Techniques
ISTC Certificate in
Technical Authorship
Course cost
£300
£320
Course launch dates
June 2006
October 2006
Course duration
To suit students’ needs
Examinations
0101 Written paper
0102 Project work
Examination dates
Examinations will start in spring 2008.
Dates to be announced.
0203 Written paper
0204 Written paper — practical
ISTC website
Work has been continuing on the
preparation of the new ISTC website
following the successful demonstration
of the prototype at Conference 2005. It
has been an enormous job getting all
the content from the existing site and
transferring it into the new one.
My thanks must go to John Lee
MISTC and to Geoff Rose FISTC for their
invaluable help in getting the site this
far. I must also thank Matthew Jennings
and his crew at Industrial Artworks
for producing the artwork and ‘look
and feel’. I am sure that you will all
appreciate the quality and professional
look of the new site.
At the time of writing, the new
site is in final testing to ensure that
there are no broken links, errors or
omissions, or other ‘bugs’. I must also
thank all those kind volunteers who
have helped me with the site testing.
Their comments and feedback have
been extremely useful.
By the time you read this, the site
should have been launched, although
content will still be being added. Please
let me know about any problems you
encounter so that we can iron them
out and present the ISTC in the best
possible light.
I intend to write an article about the
rationale behind the new site and the
features it offers for the Autumn 2006
issue of Communicator.
Once again, thanks to everyone who
has assisted me in developing the site.
I hope all the hard work pays off!
Simon Butler FISTC
E: simon@sbis.demon.co.uk
Documentation lost
in translation?
3di can help you provide
effective information to your
international customers by
managing the translation of
the information supporting your
products, processes and
services.
Typical translation projects
undertaken by 3di include:
• Software user guides
• Medical device
manuals
• EU regulatory information
• Compliance documentation
• Marketing, white papers &
sales information
• Process & procedural
documents
Call us: 01483 211533
www.3di-info.com
High Street, Ripley, Woking, Surrey GU23 6AF
ISTC news
Discussion Group
http://finance.groups.yahoo.com/group/ISTC_Discussion
Topics this quarter ranged from points
of grammar to help with software, via a
discussion about professional bodies with
which the ISTC could become affiliated.
As always, there were plenty of
requests for help with Word — unwanted
new styles, restarting list numbering,
linking images and printable areas
were all under discussion. Less usually,
there was also a request for help with
FrameMaker; specifically, with using
inline images. One of our members
asked for reasons that could be supplied
to his bosses to justify a change from
Word to FrameMaker; he was inundated
with suggestions from some very
enthusiastic FrameMaker users!
Software simulators
Revision control
Metric versus imperial
A member was interested in knowing
what methods of revision control were
used by other group members. Most
favoured using numbers to indicate
major and minor revisions, with some
also using status markers such as ‘draft’.
It was also pointed out that the reason
for giving the version also affected what
should be shown; is the revision control
for internal use only, or for end users?
When localising measurements that
are given as both metric and imperial,
is there really any point in translating
imperial measurements for languages
and countries that don’t use them? The
general opinion was that there wasn’t
much point in doing so, particularly
since, for example, a pound (weight)
in the UK is not equivalent to a pound
weight elsewhere in Europe. However,
for some industries, a direct metric
equivalent does not exist for an imperial
measurement, and both should be given.
Using Wikis for online help
The benefits and drawbacks of using
a Wiki (a website that allows the quick
addition, removal and editing of
content) to create and maintain online
help were briefly discussed, specifically
in the case of a software product that
is tailored to a client’s needs. The
main drawback, from a writer’s point
of view, seemed to be inconsistency
in the writing styles and abilities of
the contributors, and hence a need for
professional editorial input, which is
contrary to how a Wiki operates.
Embedding fonts in HTML
As part of a branding exercise, a group
member wondered if it was possible to
embed fonts in CHM help files, so that
the fonts could be viewed without the
user needing to install them locally.
Several solutions were suggested,
including creating graphics of titles
with unusual fonts, but although fonts
can be embedded into HTML pages
to be viewed in Internet Explorer, it
doesn’t seem possible to do this for
compiled CHM files.
A member was looking for ideas on how
to produce a free-standing software
simulator. Internet Explorer can be
configured for a full-screen view which
hides toolbars and menus; several
software packages were suggested,
including Macromedia Captivate.
ISTC affiliations
A suggestion was made that the ISTC
should be affiliated with relevant
organisations. The Royal Society of Arts
was suggested, with benefits of the use
of their library and a meeting space in
London; other suggestions included the
IEEE and the British Computer Society.
Candidate agreements
Have members of the group been
asked for proof of identification and
qualifications when applying for jobs
through an agency? A member was
concerned about being asked to complete
a candidate’s agreement form, but many
other members had been through similar
identity checks as a result of 2004 EEA
regulations. Many would prefer to supply
the information directly to employers
rather than agencies. A suggestion to
prevent misuse of your documents was
to create watermarked PDF versions.
Grammar and spelling
Points of grammar and spelling always
meet with lively discussion on the group;
topics this quarter included correct use
of ‘a’ and ‘an’; when something is ‘in’ and
when it is ‘on’; and whether ‘analog’ or
‘analogue’ is correct. C
Catherine Sharp MISTC
E: farfalla@gmail.com
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.
The ISTC was formed in 1972 from the
Presentation of Technical Information
Group (est 1948), the Technical
Publications Association (est 1953, later
the Institution of Technical Authors and
Illustrators) and the Institute of Technical
Publicity and Publications (est 1963).
To join the ISTC or upgrade your
membership, contact Carol Hewitt on
01733 390141 or at istc@istc.org.uk or PO
Box 522, Peterborough, PE2 5WX.
Council members
President
Gavin Ireland
president@istc.org.uk
Treasurer
Peter Fountain
treasurer@istc.org.uk
Website
Iain Wright (existing site)
web@istc.org.uk
Simon Butler (replacement site)
simon@sbis.demon.co.uk
Journal
Marian Newell
journal.editor@istc.org.uk
Education
John Young
education@istc.org.uk
Membership
Ian Wood ian.datim@freeuk.com
Marketing
Paul Ballard
marketing@istc.org.uk
Conference
Alan Fisk conference@istc.org.uk
Other members
Julian Murfitt
julian.murfitt@mekon.com
Linda Robins
review.manager@istc.org.uk
Company Secretary
Carol Hewitt
Newsletter Editor
Sophie Watson (layout and artwork)
newsletter.layout@istc.org.uk
Kathryn Valdal Fourie (content)
newsletter.editor@istc.org.uk
International Representative
Florence Dujardin
international@istc.org.uk
Member news
New members
Member
Tina Abbott
Lionel Browne
Robert Bull
Peter Grant
Roy Henderson
David Jones
Kate Macumber
Andrew Moore
Sarah Pearson
David Perry
Rachel Potts
Andrew Robertson
Adrian Shaw
John Taylor
High Wycombe
Sandhurst
Orwell
Altona, Australia
Dundee
Golborne
Fareham
Southampton
Wotton-UnderEdge
Cossington
Cambridge
Exeter
Bolton
Hornsea
Associate
Philip Armit
Barnet
Thomas Wilson-Copp Norwich
Student
William James-Allison Dereham
Claire McMillan
Bristol
Robert Tavener
High Wycombe
Anne Ward
Daventry
Transfers
Fellow
David Bird
Malcolm Blease
James Bromley
Karen Campbell
Graham Devlin
Alexander Diack
Michael Dobbins
Michael Faircloth
Christopher Haynes
Michael Gascoigne
Alun Jones
John Kenyon
Lynn McBrearty
Roger Milbury
Peter Owens
Allan Mowat
Linda Robins
Lennart Strom
Andrew Wall
Ian Wood
Tudor Wynn-Williams
Member
Jon Cruise
Marisa Fernandez
Owen Flatau
Gavin Rattray
Graham Richards
Marian Routledge
Josephine Wilson
Alice Vowles
Rejoiners
Gregory Tomes
Obituary
Shefford
Rotherham
London
Basingstoke
Linlithgow
North Ferriby
Ellon
Aylesbury
Bedford
Camberley
Sauchen
Leicester
Newport Pagnell
Maidstone
Birmingham
Oman
Aldershot
Maidenhead
Cheltenham
Corby
Borth
Thatcham
London
London
Appley Bridge
Wimborne
Coalville
Manchester
Stotfold
Bristol
The ISTC regrets to announce the death
on 22 April of former Council member
Craig Scott, after a brief and brave fight
against cancer. If anyone would like to
make a donation in his memory, Craig
supported Amnesty International and
the Born Free Foundation.
Independent Authors SIG
http://finance.groups.yahoo.com/group/ISTC_IASIG
Rates for copywriting
A local marketing company approached
Jean Rollinson to see if she was
interested in occasional copywriting
for them. Their previous copywriter
was one of the company directors (now
retired), so they had no experience of
paying for copywriting, and they asked
her to suggest a suitable rate. Jean
asked whether she should charge more,
less or a similar rate to that which she
charges for technical writing.
Peter Finch replied that he does a
modest amount of copywriting as a
change from technical writing and to
keep his creative juices active. Normally,
he charges a project price based on
a rate of £30 to £50 an hour plus
expenses. He added that it is important
to obtain a very clear brief of what the
client wants and how they are going to
use it. Copywriting is more subjective
than technical writing. A committee can
approve a technical manual, but if you
try to get a committee to approve some
copywriting, you could end up with
trouble. He recommended that Jean
makes sure that only one person signs
off the work.
Advertised rates and agencies
Advertisements containing poor rates
and unreasonable job requirements
are a source of irritation for many
technical communicators who are
looking for their next assignment.
Our president, Gavin Ireland, has
pledged to complain to agencies and
employers if we tell him about such
advertisements.
In general, the response so far has been
less than positive, with replies ranging
from ‘the client sets the rate and we can’t
complain’ to ‘thanks for your interest,
but the position has now been filled’.
On the other hand, there are
exceptions. One of our members
forwarded a copy of an advertisement
from JobServe (www.jobserve.com). The
client was looking for a Junior Technical
Author in London. The pay ranged from
£8 to £12 an hour. Gavin contacted
the agency and suggested that such a
position should justify closer to £18 an
hour if they wanted a suitable candidate.
The agency, Badenoch & Clark (www.
badenochandclark.com), replied saying,
‘…your advice was very useful. I have
given your feedback to our client and we
have now revised the rate to offer the
candidate a minimum of £18 an hour.’
What a refreshing change to come across
a responsive and responsible agency!
Unions for technical writers
Andy Smith thought about joining a
union as a freelancer because of some
of the benefits such as legal advice and
access to other services such as cheap
insurance. He asked for our advice on
unions that cater for the self-employed.
Geoff Lane suggested that alternatives
to unions were organisations that provide
those services to freelancers, such as the
Professional Contractors Group (www.
pcg.org.uk). Also, there are websites that
offer the same services without needing
to join an organisation; for example,
Shout99 (www.shout99.com) offers free
advice forums in addition to offering tax
and insurance packages. Jane Funnell
found the Federation of Small Business
(www.fsb.org.uk) to be excellent.
David Cooper wrote that many unions
cater for the self-employed because free
lancing is a way of life in some trades. (1)
The National Union of Journalists: ‘The
NUJ Freelance Directory is the biggest and
most reliable listing of media freelances
in the UK and Ireland, covering writers,
editors, sub-editors, designers, illustrators,
photographers, broadcasters, scriptwriters,
web designers, translators, trainers and
researchers’ (www.nuj.org.uk). (2) The
Writers Guild of Great Britain, which is media
orientated (www.writersguild.org.uk). (3) The
Society of Authors, which is for published
authors (www.societyofauthors.org).
Dodgy dealings on the web
Pay-per-click web advertising is a big
industry. Geoff Lane directed us to the
article ‘Yahoo Implicated In Spyware Click
Fraud’ (www.webproworld.com/viewtopic.
php?t=62397). Allegedly, the problem
stems from Yahoo partners working in
consort with spyware vendors to generate
commission for the partner. I read
around the subject: if you are thinking
of using pay-per-click (or indeed, if you
already do use it) it is well worth taking
the time to look at the issues before
you part with your money. C
Mike Unwalla FISTC
E: mike@techscribe.co.uk
10 Conference 2005
The magical number: seven ± two
Matthew Ellison explores the origin of this oft-quoted number, and
asks whether its use as a golden rule for information design is justified.
Introduction
Anyone who has worked in technical communi
cation long enough will have come across the
magical number ‘seven plus or minus two’. It’s
often quoted by trainers such as myself as a
guideline governing anything from the number of
categories of information that you should include
in a website through to the number of steps in a
procedural Help topic. Over recent years many of
us (myself included) have been guilty of applying it
without being fully aware of its origin; we typically
have some vague idea that it concerns a limitation
of the human brain that prevents us from being
able to process more than nine items effectively,
but few of us know the details of the original
research that produced the concept of this magical
number. And still fewer of us choose to question
its applicability to information design — it’s far too
convenient a rule of thumb to risk invalidating it!
This article explains the origin of the magical
number and discusses the extent to which using it
as a golden rule for information design is justified.
George Miller and The Psychological Review
The term ‘seven plus or minus two’ was coined by
George Miller almost exactly 50 years ago when
he wrote an article in the American Psychological
Association’s journal, Psychological Review.
Computers were in their infancy at that time, and
no-one had even begun to imagine graphical user
interfaces, Help files and the World Wide Web, so
clearly the concept of ‘seven plus or minus two’
was not intended as an aid for designing such
information systems. In fact, George Miller was
writing purely from the viewpoint of a cognitive
psychologist; his article made no reference to the
field of technical communication whatsoever.
The article described a variety of psychological
experiments that fell into three distinct categories:
Absolute judgement (the ability to distinguish
between musical tones or other stimuli)
Subitising (the ability to recognise numbers)
Short-term memory.
Despite the fact that these categories appear
unrelated, the experiments suggested that the
number seven was significant in all three.
Absolute judgement
George Miller cited several examples of research
in this area. A typical example is the experiment
conducted in 1952 by I Pollack: he asked listeners
to correctly identify a series of tones that were
evenly distributed on a logarithmic scale. With
up to five or six different tones, listeners rarely
confused them. But with significantly more tones,
they made frequent mistakes. The conclusion was
that most people have an upper limit that is in the
region of seven tones. Other experiments showed
that the same results hold for variations of
loudness, or brightness, or saltiness (when tasting
food), and in fact of any one-dimensional variable.
Subitising
Subitising means being able to judge the number
of a collection of randomly arranged items
more or less instantly. The common die (or dice)
used in many board games relies on a human’s
capacity to be able to recognise the numbers one
to six without hesitation. Even if the dots were
not arranged in their familiar patterns, most
people would still be able to call the numbers
without needing to actually count them.
Miller described the research of Kaufman, Lord,
Reese and Volkmann at Mount Holyoke College,
Massachusetts. They flashed patterns of dots on to
a screen for 1/5 of a second, and asked observers
to report on the number of dots. For up to six dots
there were almost no errors. Above that number,
however, inaccuracies began to creep in, and for
significantly higher numbers observers could only
provide a rough estimate. So again, seven appears
to be the significant number where change occurs.
Short-term memory
George Miller referred to a number of
experiments on short-term memory, all of
which indicated a limit of around seven items.
However, Miller was anxious to point out the
difference between these results and the ones
relating to absolute judgement. He explained that
absolute judgement is limited by the amount
of information, whereas the span of short-term
memory is limited to the number of items or
chunks. A chunk could potentially contain
multiple bits of information; for example most
of us would have no problem remembering
five three-syllable words, where the number
of actual sounds or syllables that we are
remembering totals 15. By combining (or what
Miller called recoding) information into chunks,
we can remember far in excess of seven bits of
information. That explains why long telephone
numbers are split into groups of two, three or
four numbers, and is also the principle behind
many of the tricks and methods for performing
what appear to be fantastic feats of memory.
George Miller’s conclusion
Contrary to the urban legend that has developed
around the number seven since the original article,
Miller himself was far from certain about its status
as a magical number. In concluding his article, he
11
suspected that the recurrence of the number seven
in the three categories of research describe above
was ‘only a pernicious, Pythagorean coincidence’.
His summarising remarks actually dwelt less on
the number seven than on some more general
observations relating to human limitations on
the amount of information that we are able to
receive, process, and remember. He expressed the
view that recoding is an important process that
deserved further research, and has since gone
on to oversee the development of WordNet, a
semantic network for the English language.
Applying ‘seven plus or minus two’ to navigation design
One obvious application of the magical number
is as a limiting factor for the number of items in
hierarchical navigation systems such as tables of
contents, menus and website home pages. In 1998,
two researchers from Microsoft, Kevin Larson
and Mary Czerwinski, decided to compare the
effectiveness of three different navigation structures
that all led to a set of information articles taken
from the Encarta Encyclopedia. The total number
of articles available was in each case 512 but the
navigation structures were organised as follows:
Eight top-level menu options, each leading to
eight further menu options, each leading to a
menu of links to eight different articles
Sixteen top-level menu options, each leading
to a menu of links to 32 different articles
Thirty-two top-level menu options, each leading
to a menu of links to 16 different articles.
Larson and Czerwinski set their test subjects the
task of locating specific articles using each of the
three navigation structures in turn, and measured
their performance in terms of the time taken and the
number of errors or dead-ends. To their surprise,
they found that the first navigation structure (the
only one to conform to the ‘seven plus or minus
two’ rule for the number of menu options) was
the least successful. It turned out that the number
of decisions that the subjects had to make during
the navigation process was more critical than the
number of options presented at each decision point.
Other commentators have fuelled the argument
against over-reliance on seven plus or minus two. As
D LeCompte put it in a 1999 paper for the Human
Factors and Ergonomics Society, ‘knowing that most
people can successfully remember between five and
nine items about half of the time gives us virtually
no useful guideline for design of user interfaces’.
Applying ‘seven plus or minus two’ to instructions
Is there any reason why we should be unhappy
with a procedure containing only three steps since
it falls outside the magical range? Should we limit
the number of steps in a procedure to nine (the
upper extreme of seven plus or minus two)?
The answer to the first of these questions is
almost certainly no. In fact there is an argument
that, if you need your audience to remember a set
of instructions in the correct order, then you are
pushing your luck if you include more than three
steps. The answer to the second question is: ‘it
depends’. The factors that influence the number of
steps that users can process successfully include:
The only European
Conference to focus on
software user assistance
for Publications Managers, Help
Authors, Software Developers, UI
Designers, and Technical Writers
Celebrating its tenth anniversary, this year’s European
Online Help Conference has a special focus on user
assistance tools and technologies for the future.
With the accelerating trend towards XML-based
publishing, the emergence of a new generation of
Help Authoring Tools, and the imminent release of
Windows Vista, there has never been a more critical
time to update your skills.
Top speakers
The conference provides ten sessions from
five of the world's leading experts on user
assistance:
Joe Welinske iChar James-Tanny
Tony Self iJustin Darley iMatthew Ellison
The conference venue
is one of Manchester’s
finest buildings, the
magnificent four-star
Palace Hotel in the
heart of the city
For further information or to register for the conference:
visit www.uaconference.eu or call +44 (0)1425 489 263
Two days of informationpacked sessions
Conference topics include:
i Structured Authoring
i Choosing a Help Authoring Tool
i Getting Started with DITA
i The Future of RoboHelp
i Analysis of MadCap Flare
i Preparing for Windows Vista
i Designing Embedded Help
Plus:
In-depth seminar on
Macromedia Captivate
Produced by:
Matthew Ellison
Consulting
In association
with:
Communicator
Summer 2006
12 Conference 2005
Whether they can read the instructions and
carry out the steps simultaneously
Whether they need to remember the steps, or
only carry them out as they read
Their familiarity with the context and subject
The complexity of the language
The length of each step.
According to Susan Harkus in a 2003 paper, ‘the
principle is simple: design decisions are relative to
the usage context and the nature of the information’.
Information Mapping®
Information Mapping is a widely used system
for structuring and presenting information
Matthew Ellison has
both on screen and in printed form. The reason
20 years of experience
as a trainer and user
for mentioning it here is its use of the number
seven: it identifies seven fundamental types
assistance professional
of information and recommends breaking
in the software industry.
information into no more than seven sections.
He now runs his own
The Information Mapping® method was initially
independent UK-based
described by Robert Horn in 1966 (Horn, 1966) and
training and consulting
thoroughly documented in 1969 in Information
company that specialises
in online Help design and Mapping for Learning & Reference (Horn, Nicol,
Klienman & Grace, 1969). Interestingly, the original
technology. Matthew is
documentation and justification of the method
currently working on the
makes no reference either to Miller or to any of the
next European Online
Help Conference, which is research he cited. However, I think it very likely
that Horn was aware of Miller’s work, and may
scheduled for September
well have been inspired by the idea of a ‘magical
2006 in Manchester.
number’ as he undertook the task of devising a set
E: matthew
@ellisonconsulting.com
of memorable guidelines for information design.
The benefits of Information Mapping have been
W: www.
AnzeigeCommunicator_210x143.qxd 05.05.2006 09:23 Seite 1
demonstrated though a number of tests and
ellisonconsulting.com
surveys. As an example, in 1994 the County of San
Diego surveyed more than 480 people who had
received both a traditional and an ‘Information
Mapped’ document. Of those people, over 81%
preferred the Mapped document because it was
simpler, easier to identify the main points, and
more concise. However, it is debatable whether this
proves the magical properties of the number seven.
It may simply be an indication that a document
that has been carefully structured, laid out and
signposted using common-sense principles
is easier to use than a less well structured
document — which would hardly be a surprise to
our technical communication community.
Conclusion
The use of the ‘seven plus or minus two’ guideline
in the field of navigation design and information
architecture is a tempting. However, the research
into cognitive psychology that led to George Miller’s
original article has doubtful direct relevance to our
field, and many commentators have urged caution in
treating the number seven with undue respect. Our
choice of the number of items in a list, the number
of sections in a table of contents, and so on, should
be influenced by a number of factors, not least by
the nature of the cognitive task that is presented to
the user and the existing knowledge that the user
brings to it. If we reject seven plus or minus two as a
rule of thumb, do we have a better one with which to
replace it? Perhaps three (the number of items that
almost everyone can remember in any order) is a
potential candidate for ‘magical number’ status? C
Medical technology.
The area of expertise at
mt-g medical translation.
Medicine. From all languages –
into all languages.
X Translation
X Localisation
X Terminology
X Translation management
X Process optimisation
X Layouting
X Single source publishing
Operating instructions and technical documentation, software and
service manuals. High-quality translations and translation management in the field of medical technology in accordance with the
latest CE directives. Since 1998.
mt-g medical translation GmbH & Co. KG
Eberhard-Finckh-Str. 55
89075 Ulm
Tel.: +49 731 1763 97 42
Fax: +49 731 1763 97 50
info@mt-g.com · www.mt-g.com
mt-g medical translation. Decisive quality.
mt-g is the first European medical translation
company to be ISO 9001: 2000 certified.
13
Careers
Adjusting the balance
Amanda Bates explores the role of flexible work practices — part-time,
flexitime, home working and career breaks — in the work-life balance.
There are times when the standard office-based
work pattern doesn’t work for some of us.
This may be a temporary glitch, or it may be
something more serious that needs redressing.
Whatever the specific reason, there are many
office workers interested in shifting the work-life
balance in favour of life. Over the past decade, I
have seen many articles talking about the worklife balance and ‘flexible employment’1. But can
we apply these concepts to our own working lives
as technical communicators?
With my interest prompted by my own situa
tion, I asked ISTC discussion group members and
Communicator readers to share their experiences.
This article draws upon my experience and their
responses. I have not included discussion on
such ‘flexible’ practices as ‘hot-desking’ because
I consider them to be loaded in the employer’s
favour. I have also largely ignored the freelance
option, which I know can prove very flexible;
this is partly to restrict the scope of the current
article, and partly because I have no personal
experience of freelance work.
Personal background
Credits
Many thanks to everyone
who responded to my
request for information:
Andy Smith, Damien
Braniff, Iain Wright, Jane
Teather, Mike Unwalla,
Lois Wakeman, Poornima
Kirloskar-Saini, Stella
Sorenson, Steve Rickaby
and Tom Marshall.
I’ve been working as a technical communicator
for eight years or so now, always as an employee.
Until 2004, I’d always worked full time, under
more or less standard conditions, and it had
never really caused me any problems, even
though I did, at times, miss the advantages of
flexitime that I had enjoyed while working as a
lowly clerk in local government. Then, in 2004, I
had my first child. I took the maximum maternity
leave — a year — and went back to my old job on
a part-time basis. I wanted to work — to ‘keep my
hand in’, as it were; for financial reasons; and
also for the sake of my sanity. I absolutely adore
my son, but it is something of a relief to exist in
an adult world once in a while.
Working two and a half days a week suited
me, and it suited my employer, not least
because they weren’t doing very well and it
meant they had access to my services at half the
previous price. Then the inevitable happened:
my employers’ financial crisis came to a head
and I was made redundant. At that point, I
was forced to face up to the fact that there
are not very many part-time vacancies for
technical communicators. I searched the Web,
I contacted a number of agencies and I kept a
close eye on the local press — all to no avail.
Along with a fellow ISTC member in the local
area, I investigated jobshare. Surely there were
employers who would consider the advantages
of two people’s experience and skills for the
price of one? Not, it seems, in a technical
communicator role.
I am loath to take the plunge and go freelance,
not least because the work pattern does not
suit my needs. Contracts are often time-critical,
and so require full time work, something I
don’t wish to do at present. Also, childcare
works best (for the child and, financially, for
the working parent) if it is consistent, and there
is no guarantee that freelancing would provide
anything approaching continuous employment.
But this particular tale does, I am glad to say,
have a happy ending. When I contacted a former
employer to check referee details, I discovered
that their Technical Publications department had
a need for someone to help them with a nontime-critical backlog of work. I am now working
two days a week on a short-term contract, a
situation that suits both parties for the present.
Other situations
The long summer months of job hunting and
anxiety did, however, make me think. Surely I was
not alone? Parenthood is scarcely uncommon,
after all, and it is far from the only reason that
an employee may wish to modify their working
practices. Other family responsibilities may occur;
personal injury or incapacity may necessitate a
new approach; older employees may wish to wind
down in the run up to retirement. Change may not
even be a factor; a number of my correspondents
cited a general dislike of office environments.
Flexitime
I have worked flexitime twice in my working
life. Once, as a clerk in a council office, I worked
formal flexitime. Once, as a technical author in
an IT company, I worked informal flexitime. The
latter — as I experienced it — was quite definitely
inferior. There were no rules, but neither was
there an option to save up flexitime to take a
‘flexiday’. To many, it was little more than an
opportunity to sleep in and work late. However,
such a model does offer significant benefits
over the rigid 9 to 5 — allowing, as it does, the
occasional interruption to the work routine,
without the need to obtain permission — and
seems to present few problems to the employer.
True flexitime is, however, a glorious thing.
If you know that turning up early and working
late will get you an extra day’s holiday, you’ll
do it; and usually, as a conscientious worker,
you’ll do your best to make sure that you do the
extra hours at critical times. From an employer’s
perspective, projects will be completed earlier
and staff will be happier. The disadvantages for
14 Careers
the employer are a small administration cost
coupled with the possibility of abuse.
None of my respondents talked about formal
flexitime, but several mentioned variations on
an informal version. One or two of these even
included ‘flexidays’.
Part-time working
Notes
1. Press articles available
online about the worklife balance include:
http://news.bbc.co.uk/1/
hi/business/2278695.stm
http://business.
timesonline.co.uk/
article/0,,178091341174,00.html
2. Newbury and Thatcham
Chronicle, 12 January 2006
3. Wakeman, L and Walker,
T (2005) ‘A room with
a view’ Communicator
Spring 2005, p21-23
4. Further details on
the rights of parents to
request flexible working
can be found on the
Department of Trade and
Industry website, Tailored
Interactive Guidance on
Employment Rights:
www.tiger.gov.uk
5. ‘What is the duty on
employers to consider
requests for flexible
working?’ www.tiger.gov.
uk/flexible/employer/
duty.htm
Part-time work for technical communicators
is not common. Since I lost my job, I have
had an automatic search set up at one of the
major job websites that should have found
any part-time vacancy for a technical author or
writer, anywhere in the country. I found two,
both in Leeds. Unfortunately, I don’t live within
commuting distance of that noble Yorkshire city.
Yet there is no absolute reason why technical
writing can’t be performed on a part-time basis.
I can imagine a small technology company
whose requirements wouldn’t justify a full time
author, but who might find the continuity of an
employed part-timer useful. Larger companies
may even find a requirement for a part-timer. My
current employer had a backlog of jobs that were
never urgent enough to be assigned to the regular
staff. Before I contacted them, they were thinking
of taking on a trainee who could be let loose
on these tasks; I very much doubt that the idea
of employing a part-time technical author had
occurred to them until my telephone call. As my
manager said, I — an established author with, in
this case, some familiarity of the company — was
likely to be able to get more done in a shorter
time, at a cost that I suspect is lower than a full
time novice.
Contacts aside, the easiest way to get a parttime job seems to be to convert your existing
job. The right to request such a change is now
enshrined in UK law — if you are a parent (see
‘The Law’, below, for further details).
One male correspondent bewailed the fact that
all the part-time jobs seem to go to women. He
thought it unfair (and perhaps it is), but there
are reasons for this state of affairs. Traditionally,
women are more focussed on the domestic side
of their lives, and so are more likely to want
a part-time job. Many of the part-time jobs
available (and here I am considering the wider
employment market) are in fields associated
with female workers — and relatively few of
them are well paid or well respected. A notable
exception to this latter clause is teaching, for
which one must have training and qualifications.
A fairly unscientific sample of available parttime positions can be obtained by looking in a
local newspaper. For example2, a single edition
of my local paper yielded the following parttime vacancies: retail (five) other sales (two),
healthcare (three), childcare (one, an agency
advertisement), other caring/community roles
(two), reception (one), personal assistant (one),
clerical (two), administration (three, including
one book keeper) and education (three, one
for a qualified teacher). There were also
advertisements for part-time debt collectors
(‘commission only’), a van driver, a stocktaker
and, most interestingly, a production editor/
design sub-editor (‘full or part time considered’).
Unexpectedly, there were no part-time catering
or domestic vacancies advertised this week,
but I have seen several in the past, along with
a much larger number of vacancies for parttime care workers. On the whole, the employers
offering part-time work are predominantly
in the education, healthcare, civil service
or local government fields. Technical roles
rarely feature — perhaps because of the male
dominance over this type of role and the
tendency for most workers seeking part-time
work to be female.
Jobshare
Jobshare suffers from a similar image problem
to the more straightforward part-time jobs. It
tends to be associated with female workers,
and is concentrated in education (teaching and
support roles), healthcare and local government.
If, as I have, you ask a recruitment agency — or
even an employer, if you can get close enough
to one to ask — about the possibility of a given
technical communication vacancy being open
to jobshare, the most likely response is that the
idea is very interesting… and then silence. The
more conscientious agencies will get back to
you saying that their client really wants a single
person to do the job. One extremely honest
recruitment agent told me that her client was
not interested because they would have to pay
the agency’s ‘finder’s fee’ twice. Perhaps this is
why agents find the concept so interesting.
Of course, jobshare does not suit every role.
There are additional running costs, although these
can be taken account of in jobsharers’ salaries.
The expectations of the role are all-important. If
it is likely that the shared role is to cover multiple
concurrent projects, jobshare seems a perfectly
reasonable solution. If the role is to cover a
single project, it may be more difficult.
It might be awkward for two people to
collaborate effectively on one document, but
it is certainly not impossible; I once oversaw a
project in which four authors (myself and three
contractors) worked on one, rather large, project.
Each of us took responsibility for a section, or
sections, and together we produced a serviceable
document. Of course, working together on a
single project requires communication between
the authors, and jobsharers do not tend to spend
much, if any, time in the office together. However,
there are distinct advantages to writing things
down (as most professional communicators will
be aware), and, if supplemented by occasional
meetings or telephone calls, I do not see why
notes or e-mails cannot work.
However, jobshare, like part-time work, seems
to be something that is rarely considered for
15
technical roles, and even more rarely advertised.
We did get a positive response from the
personnel department of one ‘family-friendly’
multinational, but it seems that they, in the end,
filled their vacancy with a single employee.
Home working
Working from home seems like an excellent
way to escape the office, if that is your primary
concern. Freelancers often work from home, and
it is not unknown for salaried employees to do
the same, although this is usually an occasional
occurrence rather than a standard practice. At
least twice, when speaking to employers about
advertised vacancies, I have been told that it
would be acceptable to work from home for a
significant portion of the week, after an initial
probationary period. Both of these vacancies
were situated close to the edge of my travel-towork radius, which is why the issue cropped
up. As it happened, I wasn’t offered either job,
but this does suggest that working part of the
week from home, on a regular basis, is a realistic
option. The replies I had from list members
seem to support this conclusion.
In a recent Communicator article3, Lois
Wakeman and Tina Walker discussed a number of
issues surrounding working from home. In their
own survey of home-working technical authors,
they had responses from only one employee.
Career breaks
With one notable exception, this is an area in
which the employer can exercise discretion.
I have heard of companies that maintain an
open offer of a career break to employees who
have a suitably long service history. None of my
correspondents talked about having been made
any such offer. The exception is, of course,
maternity leave. Up to a year may be taken
under UK law, with a ‘guaranteed’ job at the
end. Of course, it is possible that your job may
be made redundant during your maternity leave
(this happened to a former colleague of mine,
and I, personally, was actually quite surprised
to find that my own job was still there when I
returned to work), but any such decision should
be made regardless of your presence at work.
The law
UK employment law4 does not, in general,
protect your right to work flexibly, although it
does (since April 2003) give parents of young
or disabled children the right to request flexible
working from their employer, providing that the
employee has qualifying length of service (26
continuous weeks). Employers have a statutory
duty to consider such applications seriously.
This right is intended to encourage both
employees and employers to find solutions
that suit them both. It does not provide an
automatic right to work flexibly, as there may
be circumstances when the employer is unable
to accommodate the employee’s desired work
pattern. However, a ‘clear business ground’5 for
any refusal must be stated.
The government defines flexible working as
change to the hours worked, a change to the
times that the employee is required to work, or
working from home. Suggested forms of flexible
working include:
Compressed or annualised hours (working the
same hours over a different or variable period)
Flexitime
Home working
Job-sharing
Term-time working (unpaid leave is taken
during school holidays)
Voluntary reduced working time (a temporary
shift to part-time work).
I suspect that the most common occasion for this
right to be exercised is maternity. Certainly I took
advantage of it (although, as noted above, my choice
to return to work part-time did not discomfit my
then employers), and I know of many other mothers
who did the same. The law does not mention
the rights of employees who are not parents to
request flexible working. This doesn’t mean, of
course, that you cannot make such a request;
merely that your employer can choose to ignore
or refuse the request without any good reason.
Conclusion
It seems that the best way of altering your working
practices as an employee is from within. Your
chances of succeeding in making any changes are
a great deal higher if you are a parent, as outlined
in the section on ‘The Law’, above. Companies do
not seem to like offering unconventional working
practices to new employees, although there are
some practices, such as flexitime, that are offered
as standard by some employers. If you are not
fortunate enough to be able to request changes
to an existing job, however, it may be worth
exploiting any contacts that you may have. The
results can be surprising — as I, and (I suspect)
my once and current employers, found.
In general, technical roles do not tend to be the
most flexible in their work models. Much of this
seems to be a result of convention rather than of
necessity; the people working in these roles have
not, historically, asked for much variation in their
working practices. Some technical roles do, of
course, demand rigid adherence to conventional
hours and practices, but, for most technical
communicators, this is not the case. Our roles
tend to involve significant periods of working
alone; periods during which it does not greatly
matter where one is, or what hours one keeps.
We also tend to work on single projects, which
often results in busy periods alternating with
times when there is less to do. The large
numbers of freelance workers working off-site
serves to reinforce the conclusion that it is,
unfortunately, the rigidity of employers that
stops more flexibility being offered. C
Now working part-time,
Amanda Bates MISTC
has been employed as a
technical author for nine
years.
E: zalamanderuk
@yahoo.co.uk
16 Methods
Skills Framework for the Information Age
This standardised approach to the definition of IT skills covers technical
communicators working in this field, as Ron McLaren explains.
Why was SFIA developed?
Perceived problems
Problem: We make highlevel resource plans, but
never have the right skills
in the right place at the
right time.
Cause: We use one
method to categorise skills
for strategic planning and
a different one to describe
them in daily operation.
Problem: We can’t recruit
the right people.
Cause: Our agency does
not understand the way
we describe skills.
Problem: Some people
we recruit don’t have
the required level of
professionalism.
Cause: We confuse
technical knowledge with
professional competency.
Problem: People don’t
seem to understand
what’s expected of them.
Cause: Our job
descriptions or role
definitions are unclear.
Problem: People complain
they don’t know how to
get promotion.
Cause: Differences
between levels in our job
descriptions are fuzzy.
Problem: Our best people
leave.
Cause: We do not give
people varied work that
expands their skills or clear
career progression. We do
not know the market rate
for the people we employ.
Problem: Our productivity
is not high enough.
Cause: Our inflexible
skill descriptions lead to
inflexible working practices.
Problem: Too many
projects run into trouble;
our life cycle management
is unreliable.
Cause: We don’t have the
right skills managing the
process.
Many organisations found that they were
suffering from a set of common skills
management problems, with varying underlying
causes and solutions. Skills management involves
various activities, including planning, acquiring,
deploying, assessing, developing and rewarding
skills. These activities do not necessarily
take place sequentially — they should be
continual — but they all depend on reference to a
clear definition of the skills. This requires a skills
framework to be put at the centre of the process.
with technical knowledge. So SFIA talks about
the ability to design databases, develop software
and manage IT services. But it does not list the
databases, programming languages or IT service
management methods that might be used.
The result is a set of 78 professional IT skills,
grouped for convenience into categories, and
described in a relatively technology-free way.
The resulting skills set can be understood by
IT people, non-technical managers and HR
people alike. A tool that was not universally
understandable would simply not work.
Development
Consistent levels
In the early-to-mid 1990s, the National Skills
Task Force, the Information Age Partnership
and the Stevens Report all called for a standard
classification of IT skills. The development of
SFIA was then instigated by The Alliance for
Information Systems Skills (AISS).
The work was carried out during the period
1997-2000 in a collaborative effort by employers
and IT industry bodies, co-ordinated by e-skills
NTO (now known as e‑skills UK — the Sector
Skills Council for IT) and backed by the DTI. The
British Computer Society (BCS) was significantly
involved in this effort and made available
information from its Industry Structure Model
(ISM), which had existed for some years.
Following the development, e-skills UK, BCS,
the IEE (now known as IET) and IMIS (Institute
for the Management of Information Systems)
joined forces to form the SFIA Foundation,
which owns and maintains SFIA.
But defining the skills is not enough. The
concept of levels is essential. The skills defined
by SFIA fit into a framework of seven levels. To
assist in comprehension, each level has a short
phrase summarising the characteristic behaviour
at that level.
1. Follow
2. Assist
3. Apply
4. Enable
5. Ensure, advise
6. Initiate, influence
7. Set strategy, inspire, mobilise
Each of the levels also has a full generic definition
couched in terms of the degree of Autonomy,
Influence, Complexity and Business Skills which
one would expect to find demonstrated at that
level. For example, the generic definition of Level
5 includes, under Autonomy, the words:
Works under broad direction. Full
accountability for own technical work or
project/supervisory responsibilities. Receives
assignments in the form of objectives. Establishes
own milestones, team objectives and delegates
assignments. Work is often self-initiated.
How was this requirement tackled?
First, it was clear that SFIA could not be a pill
that the organisation could take to solve a
problem. Instead, it was developed as a tool
that enabled those intent upon improving their
skills management to do so in a rational and
consistent way, using information that has since
become a de facto standard in the UK.
It was apparent that the best approach would
not be to define a set of job descriptions. While
there was general agreement about the essential
nature of titles such as Service Manager, IT
Architect, Technical Author and Software Engineer,
it was clear that there was still considerable
variation from one organisation to another. It was
important to give people a standard, but without
inviting them into a straitjacket. So the approach
was to define the underlying skills that are present
in the various IT roles. These could then be
combined in a way that suited the organisation.
Great care was taken to avoid confusing skills
Interpreting the levels for each skill
A skill is recognised at several levels, although
none appears at all seven. For each of the levels
at which a skill is recognised, SFIA provides a
skill-specific interpretation of the level. The panel
shows the skill profile for content creation.
How SFIA is used
There is a clear difference between describing
the skills possessed by people (the assets) and
the skills required to do the jobs (the liabilities).
If organisations really want to manage and
enhance their IT capability, they would be
well advised to focus as much attention on
understanding their skills assets as they have
sometimes put into writing large numbers of
17
Skill profile: Content creation, Code: DOCM
Definition The planning, design and creation of
information content, to be delivered electronically
or otherwise. This includes managing the quality
assurance and publication process.
Level 2 Develops an understanding of publications
support activities such as drafting, illustrating,
printing, etc. Develops a broad understanding of
technical publication concepts, tools and methods
and the way in which these are implemented. Works
with colleagues and clients to create new sections
of technical documentation through all stages of
the publication process as support literature.
Level 3 Designs individual documentation plans
for documentary items. Organises reviews of
draft material. Manages the configuration of
documentary items and documentation project
files, within own area of responsibility. Organises
final review and testing of documentary items.
Level 4 Determines the documentation needs
of users. Designs individual documentation plans.
Creates drafts for review of information format and
content. Organises the production and distribution
of approved documentary items. Manages the
configuration of documentary items and document
ation project files, within own area of responsibility.
Level 5 Develops standards and procedures to
support documentation strategy. Designs overall
support information package plans. Manages small
teams of authors, ensuring that they are aware of and
work to relevant standards. Advises on appropriate
documentation formats and systems to satisfy
requirements. Organises reviews of draft material.
Level 6 Develops strategies for the delivery of support
information, including preferred media, rules for format
of content, and reprographics strategy if relevant.
Manages documentation projects, ensuring that
adequate procedures, standards, tools and resources
are in place and implemented, to ensure that the
quality of material developed by document content
creators within the organisation is appropriate.
Role profile: Senior Author
Content creation As defined above.
Level 4 As interpreted above.
Methods and tools Ensuring that appropriate methods
and tools for the planning, development, operation,
management and maintenance of systems are adopted
and used effectively throughout the organisation.
Level 4 Provides expertise and support on use of
methods and tools.
Project management The management of
projects, typically (but not exclusively) involving
the development and implementation of business
processes to meet identified business needs, acquiring
and utilising the necessary resources and skills, within
agreed parameters of cost, timescales and quality.
Level 4 Defines, documents and carries out small
projects, actively participating in all phases. Identifies,
assesses and manages risks to the success of the project.
Prepares realistic project and quality plans and tracks
activities against the plans, providing regular and
accurate reports to stakeholders as appropriate. Monitors
costs, timescales and resources used and takes action
where these deviate from agreed tolerances. Ensures
that own projects are formally closed and, where
appropriate, subsequently reviewed, and that lessons
learned are recorded.
wordy job descriptions (describing the liability).
If the mode of working needs to become more
assignment-based then the relatively short dura
tion of each assignment makes the job description
approach even more wasteful. On joining a
project, each member should receive a set of
objectives from the Project Manager, defining
that individual’s contribution to the project.
Anything else we might want to say attaches
to the individual rather than the project. Profess
ional skills and overall ability to contribute
to the organisation, to innovate, to help
others — these are all portable. The individual
carries them into the next assignment. So they
more usefully form part of what we might call
the individual’s professional identity, more
commonly known as a role profile. The panel
shows the skills element of a hypothetical role
profile for a Senior Author that requires various
skills, including content creation, at Level 4. At
an early stage in an implementation of SFIA,
the IT organisation will define its role profiles.
There will not be many of them — say, between a
dozen and twenty. Each one would have several
headings, including one for SFIA skills.
The role profiles represent different
denominations of the overall skills asset. This is
fine for any process that requires a simple defini
tion. It can be used for resource planning, for broad
organisational changes and for identifying an initial
list of candidates for a project. But people are all
different. How is that taken into account?
For each role profile, we have a standard definition
of the skills and levels that make up that type of
professional identity but the reverse of the coin is
the profile of the individual. Individuals match the
overall role profile to varying extents; in addition to
their professional skills, their technical knowledge
and experience is valued. This information is used
for the final selection of project members; it is
also used in appraisals and development plans.
Our role profile gives us a coinage of skills that
takes account of the need for summarisation but
also enables us to treat people as individuals. It
provides a set of definitions that can underpin all
activities in the skills management process.
Does it work?
SFIA is simple and can be widely understood; it is
now used by many commercial organisations and
Government departments, including the Ministry
of Defence. Last year the Government introduced
SFIA as its preferred IT skills framework.
The feedback from users makes it clear that
SFIA is an effective tool for any organisation
intending to improve the way it acquires, develops
and deploys IT skills. Furthermore, there are now
several commercial partners adding value to the
framework. So SFIA can now be used as a guide
when searching for training, and is amenable to
being recorded in a skills management database.
As the common language of skills, SFIA is a
powerful tool for IT skills management. C
Note
Ron McLaren will be
speaking about SFIA at
the ISTC’s Conference on
4 October 2006.
Ron McLaren is
Operations Manager of
the SFIA Foundation,
which owns and
maintains the SFIA. The
Foundation’s members
are BCS, e‑skills UK,
the IET and IMIS. An EndUser Licence is available
free of charge for those
intending to use SFIA for
the internal management
of their IT skills. Feebearing licences are
available for organisation
intending to use SFIA
to support product or
service offerings.
E: ron.mclaren
@sfia.org.uk
W: www.sfia.org.uk
18 Project profile
User training with OnDemand
Dirk Manuel describes how he used OnDemand Personal Navigator
to provide training exercises to users of a global system.
This is my fourth large ERP (Enterprise Resource
Planning) project for the same client. Although my
role has largely remained the same, each project
has introduced new tools and new challenges. This
project, the G‑ROC project, has been no exception.
I joined the project late. My involvement on
another project meant that, by the time I was
brought on board as the Documentation and
Training Lead, many of the important decisions
had already been made. The software had
been chosen, including Global Knowledge’s
OnDemand Personal Navigator. Never having
used this product before, I was about to embark
on a very short and very steep learning curve.
The G-ROC project involves ExxonMobil
implementing a new retail system in all its
convenience stores worldwide (such as the On The
Run shops attached to the Esso, Exxon and Mobil
petrol stations and shown in Figure 1). The system
is based on an SAP platform, and effectively
consists of two components: the SAP Retail System
(SRS), which runs in the stores and is used by the
Store Managers, and the HQ system (SAP R/3),
which runs centrally (in Dallas) and is used by the
‘above site’ support staff. Although SRS and R/3
are connected, and share data, they are effectively
separate systems, providing separate functionality,
having separate interfaces and being used by
separate user groups. Training had to be provided
for both systems, and one of the key components
of the training package is hands-on exercises.
For the SAP R/3 system, exercises are provided
in a dedicated training environment, which is a full
copy of a live system. We set up dummy data and
the trainees logged on and used the system exactly
as they would in ‘real life’. For the SRS system,
things are a little more complicated. Firstly, whereas
the R/3 users are located at headquarters where
they have dedicated network connections into the
systems, the site users access the system through
Figure 1. An On the Run shop at an Esso petrol station
the Internet, using a Broadband, satellite or, in some
cases, dial-up connection. With a heavily guarded
firewall between the stores and headquarters,
providing a path to a training system on the
other side of the firewall is simply not an option.
Capturing data
Even if it were possible to provide access to a full
training system, many of the site activities are
time-sensitive (that is, they must be carried out at
certain times) or event-triggered (that is, they are
only carried out in response to specific events).
This makes the setting up of realistic exercise data
both difficult and error-prone. Because of these
complications, it was decided to provide standalone
simulations, which have the same look and feel as
the system but which are actually recordings that
can be run locally, in isolation from the system.
This is where OnDemand Personal Navigator
came into play. It is an application that enables
you to capture system activities, and then create
demonstrations and/or exercises using this
recording. It comes in several flavours, depending
on the application(s) you want to record. For our
project, we bought the SAP Package but packages
also exist for PeopleSoft and Siebel. The relevance of
these packages is the context-specific information
that OnDemand captures — in terms of recognising
the names of the buttons clicked and the fields into
which data has been entered — during recording.
As the project had already been running for
a year, the first suite of OnDemand exercises
had already been developed and used in training.
At the time that this first suite was developed, the
project lacked the in-house OnDemand skills and
so development had been outsourced to thirdparty consultants. We were now approaching
the second wave of implementation, and it was
time to update the exercises to reflect the latest
system functionality and design. The initial plan
19
was to use the same consultants to perform the
updates. However, they were unavailable owing
to commitments at other clients. Before shopping
around for alternative consultants, I thought
I’d have a quick look and see just how much
work was involved. I’d had some experience of
developing prototypes for interactive training
using Macromedia Flash (painful!) so I reasoned
that it couldn’t be that difficult.
I went through the existing exercises (for the
first time…) and wasn’t terribly impressed with
either the quality of the material, or the apparent
capabilities of OnDemand. So I printed out the
entire 260-page OnDemand Developer’s Guide,
and spent a couple of evenings on the sofa finding
out exactly what it could do and how we could use
these capabilities. (Incidentally, this is an approach
I would unreservedly recommend when
starting to use any new content development
application — find out what it can do and then
think of ways of using those capabilities. If you
decide what you want to do first, and then look
for how to implement what you want to do, you
will always be constrained by your own vision.)
During my read-through of the User Guide, I
soon learned two things: Firstly, the ‘experts’ who
initially developed our exercises clearly had no
more than a rudimentary grasp of OnDemand’s
capabilities. They had simply captured the basic
system actions using all the default OnDemand
settings, without providing any additional function
ality or configuring OnDemand to meet our
requirements. Secondly, there is a lot you can do
in OnDemand to build well-rounded, user-friendly,
realistic simulations. I decided, therefore, that
I would dispense with the consultants’ services
and simply do everything myself. In truth, I
really couldn’t justify paying someone more
than I earn just to produce something of a lesser
quality than I could produce myself.
Capturing tasks
My first task was to re-capture all of the exer
cises (plus a handful of new ones for the new
functionality). This was done by setting up data
in one of our development environments, and
recording the tasks in those systems. Because the
final recording is independent of the environment
it was captured in, I was able to capture different
exercises in different environments (we have
several) depending on which one happened to
have the data (or configuration) I required. I could
also capture the hard-to-recreate scenarios in the
live system, bypassing data set-up altogether.
At this point, it is worth noting that OnDemand
is not a ‘recorder’ in the sense of a video recording.
It does not capture an activity over elapsed time in
the way that, for example, Camtasia does. Instead,
it captures an image of the screens displayed, and
the user actions (key-presses or mouse-clicks)
taken at each screen. Also, this information is not
automatically captured — you don’t start recording,
do your work, then stop recording and voilà it’s
Figure 2. Editing instructions in OnDemand’s developer workplace
done. You need to press Print Screen each time you
want to capture a screenshot or an action.
The limitation of this approach is that you
need to capture a screenshot (by pressing
Print Screen) for every action that you want to
capture, even when you are really on the same
screen. Consider the case where the user selects
a value from a drop-down list. You have to
capture the screen, click the drop-down button
(to display the list) capture the screen, select
the option, capture the screen with the option
selected in the list, and finally capture the
screen to show the selected option in the field.
Achieving context sensitivity
When capturing an action, OnDemand generates
a textual instruction for that action, based on
customisable templates. In so doing, it makes
a reasonable attempt at capturing the context
of the action. For example, in SAP, if you click
on
, OnDemand correctly identifies this as
the ‘Save’ button; it generates the instruction
‘Click the Save button’ and identifies Ctrl-S as
an alternative action automatically. However,
this context capture isn’t entirely foolproof. It
sometimes does not work, especially for webbased applications (which SRS is); for these,
OnDemand typically generates all instructions
as ‘Click the indicated link’. Not too helpful!
My second task, therefore, was to edit the
instructions (Figure 2). This proved much harder
than I anticipated, due to OnDemand’s four play
modes:
See It! The user sees an automated playback
of the recording — a demonstration.
Try It! On-screen instructions guide the user
through actions — a traditional exercise.
Know It? The user performs actions with little
or no guidance — a test.
Do It! Instructions float above other windows
on the desktop, providing guidance while the
user works in the live system — a job aid.
20 Project profile
Translating instructions
Figure 3. Within hours of my training, business trainers were teaching end-users
The different play modes significantly extend the
shelf-life of the exercises, by enabling the same
recordings to be used for multiple purposes.
The disadvantage is that each mode typically
requires slightly different text. For example, in
Try It! mode, I wanted the instruction to be ‘Enter
invoice number 123 in the Ext. ref. field’. In Know
It? mode, the user needs to know the value (it is
unrealistic to expect them to guess) but I didn’t
want to give them any additional help, so the
instruction needed to be ‘Enter invoice number
123’. For Do It! the user needs to know what to
enter where, but clearly shouldn’t see the exercise
data values. Therefore, the instruction needed to
be ‘Enter the invoice number in the Ext. ref. field’.
OnDemand facilitates this quite well, enabling
you to tag text for the various modes in which it
should appear. It tries to do this automatically
during the recording, but the results are often
clumsy and unnatural, so I still had to go through
and rework (or rewrite) almost every generated
instruction so that it made sense in each mode.
Adding business context
Dirk Manuel MISTC is
Training and Documentation
Lead for the G-ROC Project
at ExxonMobil.
E: Dirk@
TechnicalAuthoring.com
W: www.
TechnicalAuthoring.com
OnDemand can only capture the mechanics of
the task; it obviously cannot generate businessspecific information, such as where on the printed
invoice to find the payment reference number. It
also does not know anything about your business
processes, rules and guidelines. Without this
information, you are only telling trainees half
the story and so, again, I had to go through the
exercises and add the business context.
My final task was to add the bells and whistles
that OnDemand supports, things the original
developers bypassed but which make a more
rounded, more user-friendly product. This included
adding hyperlinks to other documents, branches
within exercises to support alternative scenarios,
jump-in points, explanatory pop-ups, glossary
definitions and supporting PDF documents (such as
an invoice to support the invoice entry exercise).
As the project is global and most users are store
operators with only basic English, the exercises
had to be translated. OnDemand offers no support
for multiple languages and so, for each of the
six languages required (Spanish, Italian, German,
French, Dutch and Norwegian), I needed to make
a copy of the exercises and have translators
overtype the English text with the foreign-language
version. This is painful enough, but trying to cater
for the different texts for the different modes (all
in a painfully-small textbox) is a major activity.
Maintenance will be painful because each
language is now an independent course. If screens
or actions change, they will need to be changed
in every local language course. Again, OnDemand
provides no help in this area, which means that
you must either record the exercises several times
or scrabble around in cryptically named source
folders in the bowels of OnDemand, trying to
locate the correct screens to replace.
Getting the business to buy in
One of the biggest problems I foresaw when I
started to update the exercises was getting the
business trainers to use them. Most had seen the
previous versions and (sadly, quite justifiably)
considered them to be ‘almost worthless’. To
mitigate the possibility of this response, we
asked the trainers what they thought was wrong
with the existing exercises, and what they
wanted in a suite of exercises, before we started
the updates. We also gave them the opportunity
to review the reworked exercises before we
published them. Happily, this time around we
‘exceeded their expectations’, and they were
eager to start using the new exercises at the next
available opportunity (Figure 3).
The whole project took three or four weeks of
very long days, at the end of which we had 44
new exercises on the latest functionality. It was
definitely harder work than I thought it would be,
but I am also much more satisfied with the results
than I thought I would be. In addition, the project
has been a great learning experience, and I can
now justifiably add ‘OnDemand Expert’ to my CV.
I have also learned that OnDemand can be
used to produce very effective, extremely usable
training exercises. There are limitations, but
most of these are on the development side of
things and I am generally of the opinion that
developer pain for the sake of user ease is
an acceptable trade-off. Would I use it again?
Absolutely. Would I recommend it? Without
hesitation (but be warned: a licence is $10,000).
There was another bright side to the activity.
My manager decided that it would be best if I
explained how the exercises worked, and how
they could be used as a part of a comprehensive
training programme, to the business trainers in
person. As the next implementation of the
G‑ROC project is in Central America, this meant
a quick business trip to sunny Honduras! C
Writing for global markets?
Bring the words of the world to your fingertips
With an increasingly competitive global marketplace, communicating clearly and
consistently in the language of your customer is vital. But writing for global markets
is not easy and inconsistencies in source content can delay international product
launches and damage your global brand.
SDL AuthorAssistant is innovative new technology that empowers global authoring.
Now you can:
• Leverage previously written content from anywhere in the business
• Easily find and apply approved global terminology
• Automatically perform checks against corporate writing standards
And all this without changing from your familiar authoring tool, such as Microsoft
Word, Adobe FrameMaker, Blast Radius XMetaL and Arbortext Editor.
To learn how you can put the world at your fingertips
visit: www.sdl.com/author
SDL International is the world’s leading provider of
global information management (GIM) solutions.
22 Tools
Review of MadCap Flare version 1.0.2
Carol Johnston investigates whether the latest Help authoring tool
is likely to tempt Help developers away from their old favourites.
Introduction
Installation
MadCap Flare is a new Help authoring tool based
around an XML editor. (As far as I know, to date,
it is the only one.) The MadCap development team
includes the people who created RoboHelp. The
RoboHelp product is now owned by Adobe and its
future development is uncertain. So migrating to
Flare is particularly attractive for RoboHelp users.
Because of Flare’s RoboHelp roots I will be
making some comparisons between the two
tools as I go along.
To install Flare you must first install the .NET
Framework version 2.0.x. This, in turn, requires
Windows Installer version 3.0. Both can be freely
downloaded from a number of sources. (Soon the
.NET Framework will be a Windows update anyway.)
I had some problems finding an increment of
.NET Framework that Flare would accept. The first
successful one I found was version 2.0.50727.42.
The user interface
Flare’s user interface is highly configurable
(Figure 1). You can determine where and how
different areas are displayed (on the left or
right, dockable, auto-hide, floating). This is an
innovative feature, but I recommend beginners
only start experimenting with it after becoming
comfortable with the default view settings.
The main working area is a tabbed interface. This
means that you can have many different project
‘elements’ (for example: topics, the Styles Editor
and the TOC Editor) open at the same time. This
makes it easy to jump from one element to another;
a much more efficient way of working than having
to close one thing before opening another.
Outputs
Figure 1. User interface, showing a topic in the XML Editor
Flare provides four output formats:
1. DotNetHelp: A new Windows Help format, developed
by MadCap, that also supports .NET applications. It
has a special viewer (the Flare Help viewer), which
is freely distributable. The viewer looks very similar
to Flare’s own user interface (Figure 2).
2. Microsoft HTML Help: This is the standard
Windows Help format.
3. WebHelp: An uncompiled format for browserbased Help, this is similar to RoboHelp’s WebHelp.
4. Microsoft Word: For printed documentation, this
requires Word 2003 with service packs. As I have
not upgraded to Word 2003, I can’t test this output.
I do know, however, that (unlike RoboHelp)
links and cross-references are preserved.
Targets define the output format, location and
other settings. You generate an output by ‘building
a target’. You can create your own targets. (This is
equivalent to RoboHelp’s single source layouts.)
Creating topics
Figure 2. DotNetHelp viewer
Surprisingly, creating a new topic in Flare is a
fairly laborious task. Firstly, in the Add New
Topic dialog, you enter the file name but you
can’t enter the Topic Title. After the new topic
has been created, it appears with the default text
heading ‘Topic Title’. To give the topic a sensible
title you must open up the topic’s properties
dialog and enter the Topic Title there. This doesn’t
23
update the text heading, so you need to change
this to reflect the new Topic Title. (RoboHelp’s
process is slicker. RoboHelp also replaces spaces
and illegal filename characters with underscores.)
The XML Editor
You edit topics in the ‘XML’ Editor. (In Flare,
topics are actually XHTML files. XHTML is a
recasting of HTML with XML syntax.)
Most authoring tools protect you from having
to understand and work with the underlying code.
Writing in XML, however, requires adherence
to the ‘rules’ set out in the XML schema. This
means that an XML editor must make the author
aware of what he or she can and cannot do.
Flare’s XML editor is no exception. Writing and
styling the content (see Styling below) takes some
getting used to. If you are not familiar with the
concepts of tagging and blocks of elements, you’ll
find it very difficult to understand what’s going on.
block bars
span bars
Important toggle views
There are several very useful view features in the
editor that can be toggled on and off. They give you
a clearer picture of the structure of your document
and also make it easier to change certain aspects
of the content. The most significant are block
bars and span bars (Figure 3).
Block bars indicate the various blocks of XML
content (for example: headings, paragraphs, lists),
and span bars indicate the inline (span) XML
elements (for example: strong, italic, image, index
keyword). Index keywords are discussed later.
Figure 3. XML Editor, with index keyword tags in green
Styling
Styles are stored in CSS (Cascading Style Sheet)
format. Again, most authoring tools protect
you from having to understand and work with
the underlying CSS code. Most of them also
have to make some clumsy compromises.
MadCap, on the other hand, has grasped the CSS
nettle — requiring Flare users to have some basic
understanding of CSS coding.
In the XML Editor, the process of adding styles
to text is confusing, but having said that, the CSS
Editor itself is very well thought out (Figure 4). It
provides direct access to the style sheet elements,
classes, pseudo classes and their properties. There
are some useful options for filtering the view to
display only certain types of these at a time.
Table of contents
In Flare, TOCs are easy to create. Flare also
supports the unusual but useful feature of
multiple TOCs. This means you can:
Link TOCs together to create a modular TOC
Create what are, essentially, TOC fragments
that can be reused within other TOCs.
Index
Flare has no designer or editor for creating an index.
The index is not actually built until you generate
your output: you simply insert or copy keywords
Figure 4. CSS Editor
into the appropriate topics. In other words, you
can associate relevant keywords with a topic but
you can’t associate relevant topics with a keyword.
This is something that many authors will miss.
On the plus side, there are three useful methods
for creating index terms from topics. Also, you
can create keywords within the text to act as
bookmarks for the index. When the user selects
such a keyword, the topic opens at that bookmarked
position. (See the green keyword tags in Figure 3.)
24 Tools
Other standard Help features
The following standard Help features are simple
to create and modify:
Links: jumps, popups, expanding text, dropdown text, cross-references and bookmarks
Help controls: related topics, see also links,
index keyword links and shortcuts
Graphics: linked graphics and image maps
Browse sequences.
Context-sensitive Help
Flare makes the implementation of context sensi
tivity for Microsoft HTML Help very simple. In fact
it provides a more intuitive process than RoboHelp.
Importing
Currently, from within Flare you can only import
RoboHelp projects and Word documents. Importing
Word documents requires Word 2003 with service
packs so, again, I can’t comment on this function.
Importing RoboHelp projects
I tested this feature with three different RoboHelp
projects, including one created with RoboHelp X4 (the
version before the current one). Flare did a good job.
Importing HTML files
You can’t import HTML files through the Flare
interface. However, it can be done using Windows
Explorer by copying the HTML file to the correct
subfolder of your project. When you open the HTML
file in Flare, you are prompted to convert it to XML.
Cool features
For me, the following features stand out.
Templates
Having worked in
information design
for over eight years,
Carol Johnston has
extensive experience of
managing (and writing
for) documentation
projects and of using
many major authoring
tools. She has an MA from
Cambridge University and
a post-graduate teaching
qualification. Carol is also
an accomplished trainer
and communicator,
developing many of
Cherryleaf’s courses. A
Certified Technical Trainer
and previously a Certified
RoboHelp Trainer, she has
taught and presented in
America and Europe.
E: carol@cherryleaf.com
W: www.cherryleaf.com
Any object in Flare (for example: topics, topic style
sheets, table style sheets, TOCs) can be stored as
a template. When you create a new instance of an
object, you can choose to base it on a template.
This provides consistency and saves time.
The term template, as Flare uses it, is a bit
misleading though. Templates are a starting
point. They are not permanently associated with
the new Flare object. Editing a template does not
update all the objects that were based on it.
Creating your own templates is a bit fiddly. The
process involves working outside Flare, in Windows,
to set up a file structure for the templates to reside in.
Master pages and proxies
The ability to create master pages is a very
powerful feature. It is equivalent to RoboHelp’s
templates. Master pages go beyond this though
with the use of proxies.
Proxies are objects that you can insert into your
master pages that implement particular features
on generation of an output. There are seven types.
For print outputs: glossary, index, TOC, page
header/footer
For online outputs: body, breadcrumbs and
mini-TOC.
The online proxies are worth describing here:
The body proxy performs the same function as a
RoboHelp template: you enter content that will be
replicated in all pages of your generated target.
The breadcrumbs proxy outputs a trail of links
across the top (usually) of all topics. Users can see
where they are in the hierarchical TOC structure
and can also click on the links to go back up
the trail. (See the purple links in Figure 2.)
The mini-TOC proxy creates a set of links to
the topics that are below the current topic in
the TOC hierarchy.
Conditionals
You can apply conditional tags to any type of
content (blocks of text, pictures, tables and even
rows and columns within tables). When you edit or
create a build target, you can specify which condi
tional tags to include or exclude from the output.
A useful touch is that their conditions can be
seen instantly in the Contents Explorer by the
use of little colour-coded squares next to them.
Variables and snippets
Variables and snippets are particularly useful and
time-saving. They allow you to reuse content that
you want to appear in several topics without having
to cut, paste and keep track of any changes you
make. Variables are short unformatted pieces of
text, for example: a company name. Snippets are
formatted chunks of content. Changing the ‘value’ of
a variable or editing a snippet updates all instances
of it within the content, ensuring consistency.
Glossaries
This is a neat feature. You can create terms and
definitions both in the Glossary Editor and ‘on
the fly’ when editing topics. There are options to
have Flare create auto-link instances of glossary
terms within topics to pop up the definitions.
Flare’s own Help system
Besides being extremely useful and well written,
Flare’s Help system is a good example of embedded
Help. It is part of the user interface and comprises
the usual features (TOC, index and search) plus
‘dynamic’ (context-sensitive) Help. In particular, there
are lots of short movies to explain and demonstrate
features and also information on ‘best practices’.
Conclusion
Overall, I was highly impressed with Flare’s rich set
of useful features. However, in providing all this extra
functionality, MadCap seems to have overlooked
some useability aspects of more fundamental
requirements — in particular, creating topics. There
are also some niggles and bugs along the way, but
this is only the first release and they will be ironed
out as the tool matures. An update to version 1 is due
shortly and version 2 is planned for September.
In summary, Flare’s future looks bright, but it is not
a tool for authors unwilling to get their hands dirty
with a bit of XML and CSS coding knowledge. C
What kind of ROI can I actually
get from DITA, XML, and the rest?
Take advantage of the Mekon Content Strategy Audit Discount Offer and find
out what changes you could make to get more with less in your content budget.
With 15 years supplying implementation and consulting services in the content solutions industry, Mekon can
analyse and optimise your processes and systems. We enable companies to reuse content, balance corporate
consistency with local control, eliminate manual formatting for multi-channel publishing, and choose and
implement the latest in content and translation management technology.
Mekon is the UK’s leading DITA and XML content solutions consultancy organisation. With accepted industry
averages like these, it might be to time to re-evaluate your processes and tools:
~ 30% of content creation costs can be saved through reuse
~ 70%-90% publication process cost can be recovered through automation
~ 40-60% of translation costs is actually reformatting. Translation Memory saves even more
Visit www.mekon.com/istc to request a Content Strategy Audit Quotation and
to download a free whitepaper on why DITA is changing the content industry.
for more information on how Mekon can change your business
t +44 (0) 20 8722 8400
e info@mekon.com
w mekon.com
26 Book review
David Pogue and the missing manuals
Linda Robins investigates the hit series and the man who created it,
while Richard Truscott summarises key aspects of its style.
With countless books and broadcasts to his
credit, David Pogue may well be one of the most
famous technical communicators in the world.
His down-to-earth style is cited as an inspiration
by many technical authors. This book review
special introduces the man and his work.
So who is David Pogue?
When most titles in a series are best-sellers for
David Pogue with the missing manual
for Mac OS X, Tiger Edition
their topics, the man behind the phenomenon
is of interest. A visit to www.missingmanuals.
com reveals more about him. David Pogue is
introduced as a pianist, a former conductor on
Broadway, and as a magician. Further details are
given as summarised in the short biography on
David’s own website:
‘David Pogue, Yale ‘85, is the weekly personaltechnology columnist for the New York Times
and an Emmy award-winning tech correspondent
for CBS News. With 3 million books in print,
he is also one of the world’s best-selling howto authors. He wrote or co-wrote seven books
in the “for Dummies” series (including Macs,
Magic, Opera, and Classical Music); in 1999,
he launched his own series of complete, funny
computer books called the missing manual
series, which now includes 30 titles. David and
his wife Jennifer Pogue, MD, live in Connecticut
with their three young children. His Web page is
http://www.davidpogue.com.’
Here you can also discover more about
his New York Times column — actually two
columns each week, one appears in the printed
newspaper and the other, which is ‘shorter,
funnier and more casual’ goes out by e-mail to
anyone who signs up on the website. You will
also find David’s daily web log, spoof songs
and cartoons (as well as past New York Times
columns).
David Pogue believes that his background
is what makes the missing manuals series
a success. In an interview with Jennifer
Buckendorff (from 17 December 2002) posted
on www.missingmanuals.com, David explains
that it is because his background is unusual that
his approach matches that of his reader.
‘I came very late to computers, so I’d never
even touched one until my senior year in college.
To this day, I believe the fact to be my ace in the
hole. I’m one of them. I’m one of the newcomers.
‘I am not one of the insiders at all so in
everything I do I try to bring that point of view.
People still aren’t really designing for people
who are not computer people. And so that’s
what I try to explain in the books, and that’s the
point of view in the Times reviews, and so on.’
David sees his approach is that of a real-world
person. The style David uses aims to bridge the
gap. To maintain his understanding of what
users want (despite now being immersed in the
business) he also checks e-mails, websites and
forums to discover the type of questions that
users are asking.
The tips given in the books, and those in David’s
columns and blogs, are evidence of this approach.
27
Missing Manuals Author’s Guide
Richard Truscott read this guide with a view to
gleaning ideas that might be useful to Communicator
readers. Among the common sense that might not
come as news to experienced technical authors, he
found useful ideas that he now uses in his manuals.
Act as the reader’s guide
Your manual must be an intelligent advisor for the
reader. It must not be a dry guide to how the software
works; it must be as if you had a knowledgeable
and patient friend at your side as you learn to use
the software. This is probably the most fundamental
idea for missing manuals because, conventionally,
manuals describe the software based on its features.
The missing manual starts by showing the user
how to do common tasks. The dry description of the
software’s functions is relegated to an appendix.
Structure of the manual
A manual contains introductions to the whole
book and then to each chapter and section. These
introductions are there to orientate the reader;
they must be clear about what is being described.
The book introduction starts with a brief and
friendly introduction to the topic. If the software is a
new version, it should highlight the new features.
It should give high-level information about what
is in the book, but without a lot of detail. It should
describe any conventions used in the book and any
prior knowledge or skills that readers need. Chapter
introductions should state the problem that the
chapter is going to solve or introduce the task that
it is going to describe. Section introductions are
similar to chapter introductions, describing in more
detail the particular problem that each section solves.
Presentation of the manual
Sidebars are used to keep the main river of prose
suited to the typical reader. Basic information for
novices and advanced information for experts
are most commonly put into sidebars, along with
frequently made errors or frequently asked questions.
Hints, tips and warnings should be presented
using panels and, if possible, out-dented to start
at the left side of the page.
Step-by-step instructions on how to do a task
should be presented using numbered lists.
Cross-references should include the page
number as well as the heading text.
Figures should:
 Occupy the full width of the text
 Be placed after the cross-references to them
 Be labelled using callouts and annotations
 Have a drop shadow when they show full
screens or dialogs
 Have one or more faded edges when they show
parts of screens or dialogs (to indicate omission).
Language style of the manual
The text should:
 Use the second person, not the first person or
the passive voice
 Set actions in the present tense and in the strict
order that they happen
 Avoid sentences that start with ‘there’
(for example, ‘there are four uses for…’)
 Avoid ‘this’ and ‘these’ where the antecedent is
not clear
 Avoid jargon
 Place ‘only’ after the verb in sentences (usually
later than writers think).
And what is a missing manual?
The missing manual is ‘the book that should have
been in the box’. The series, which is a collaboration
between O’Reilly books and Pogue Press, covers
popular computer products and provides the
printed guide that is not included with the product.
Once I started looking at this subject, what struck
me forcibly was how easily we have come not to
expect there to be a printed manual when we buy
commercial software. When did things change?
Perhaps five or ten years ago, with the introduction
of embedded or online Help, which was seen as a
substitute? But there are limitations to Help when
one is becoming familiar with a new product — not
least, the ‘dotting about’ that it entails.
In my current working environment, we
produce printed user guides as well as
embedded Help pages and web-based Help
because all are relevant and useful.
As well as providing the book that should have
been there, the missing manuals series offers a
fresh approach to the formal guide to software.
The blurb on the back cover gives an indication:
‘The missing manuals are witty, clearly written
guides to popular computer products and topics.
Originally conceived and developed by best-selling
author and New York Times columnist, David
Pogue, the series has expanded to cover a broad
range of subjects. Each carefully crafted book
offers practical guidance and advice to help you
get the most out of the computers in your life.’
Available as a PDF file on the missing manuals
website, The Missing Manuals Authors’ Guide
explains how missing manuals differ in tone and
style from more formal manuals. The adjacent
panel summarises some key points, as identified
by Richard Truscott. Individual titles differ in
scope and weight but the Authors’ Guide ensures
that their inclusion in the series is appropriate
and that readers’ expectations are fulfilled.
The missing manual
is ‘the book that
should have been
in the box’.
How do they compare with the competition?
If you browse in most town-centre bookshops
or on the Internet, you will find several manuals
that appear to hit the same note as the missing
manuals series. The friendly, witty approach
is perhaps most obviously paralleled in the
‘for Dummies’ series (to which David has
contributed). I sampled some comparable titles
and found that, while the missing manuals adopt
a ‘familiar’ tone (with the reader as ‘you’ and the
debunking of computer jargon), they are more
‘serious’ in approach than the ‘for Dummies’
books. The latter can, for computing subject
matter at least, seem too flippant at times.
In examining the diagrams in a selection of
guides, I found some of those published by
Microsoft (sold separately from the software!)
provided the clearest and most colourful
screenshots. The missing manuals have a
consistent approach to presenting figures and
representing screenshots and dialog boxes,
which makes them particularly easy to use.
28 Book review
Want to read one?
In print
There is a growing list of titles in the catalogue.
I’ve selected three to give you some idea of the
scope of the series and the practical application
of The Missing Manuals Authors’ Guide.
Windows XP for Starters by David Pogue
(November 2005)
I selected this partly for the subject matter,
software with which many readers will be
familiar, and partly because it is a title in a new
subset of the series, the ‘for starters’ missing
manuals. With its caption, ‘Exactly what you need
to get started’, this subset is designed to draw
the user’s attention to the application’s most
useful features. The style is advertised as being
the same as the other missing manuals, differing
only in a new user-friendly format that features
larger print and extensive visual examples.
Designed for beginners and more experienced
users alike, with step-by-step tutorials, the book
contains some 380 pages. The background to
Windows, coverage of concepts and much of the
explanatory material is excellent for the firsttime user. The book is subdivided into desktop,
components, Windows online, beyond the basics
and life on the network.
Creating Web Sites by Matthew MacDonald
(October 2005)
I chose this manual for three reasons: the subject
is of wide interest, David Pogue didn’t write
it (so it gave me a chance to see how much, if
any, difference the author makes) and, strictly
speaking, there isn’t a manual missing (it is not
about a product as such). Matthew MacDonald
answers this point straight away: ‘No one owns
the Web; so no one has the responsibility to teach
it. If the Web did have a manual, this would be it.’
This book’s 540 pages are subdivided into
welcome to the Web, building better Web pages,
connecting with your audience, Web site frills
and blogs. Throughout, the author challenges
the reader to think carefully about motivation
and requirements for the website; the examples
are very powerful in reinforcing the importance
of this. The two HTML editors recommended
are (unsurprisingly) Macromedia Dreamweaver
and Microsoft FrontPage, but the guide is not
promoting a product.
The appendices — ‘HTML Quick Reference’ and
‘Useful Websites’ are comprehensive and clear,
for frequent ready reference.
Does the author make a difference? I could tell
that Creating Websites was not written by David
Pogue, as it lacked the personal touches that are
now familiar to me from David’s columns and
website. However, the book is an endorsement of
the missing manuals ethos and a demonstration
of the effectiveness of the Author’s Guide. Matthew
MacDonald delivers what the series promises.
Mac OS X Tiger Edition (covering Mac OS X 10.4)
by David Pogue (third printing January 2006)
David Pogue is credited as the best-selling Mac
author and this book as the ‘#1 selling Mac
book’. The Mac was David’s starting point in
computing, and his introduction sets the scene
clearly and succinctly for the reader in the
context of the evolution of Mac software, the
items of interest for the experienced Mac user or
aficionado.
This manual is a heavyweight tome at 850
pages, with a smaller typeface and greater
density of material on each page than the more
lightweight and middleweight titles. It identifies
Mac OS X as a stunning technical achievement,
about which Apple tells the user very little!
David tells the experienced user ‘What’s new in
Tiger’ in the introduction.
At the top-most level, the manual is
subdivided into desktop, components,
technologies and online. There are detailed
appendices, including one on installing 10.4
and one on troubleshooting. David uses ‘Power
Users’ Clinic’ panels to good effect throughout.
Online
Interestingly, despite the emphasis on the
printed book, the missing manuals series offers
some useful online extras.
At the back of each book, there is the outline of
a CD-ROM where the accompanying disk would
normally be. The message given is, ‘There’s no
CD-ROM in this book. You’ve just saved yourself
$5.00. Instead, every single piece of add-on
software mentioned in this book is available at
www.missingmanuals.com. There you’ll find a
tidy list of the shareware programs described in
the book, ready for you to download.’
On the website, you can also sign up for an
e-mail newsletter and to be advised of new titles
and updates to the articles and samples on the
website.
If you buy a missing manual, you are supplied
with a key that enables you to access the
document online free for 45 days using the
O’Reilly Safari Books Online facility. In addition,
there is a facility that may interest corporate
users of the series. You can subscribe to the
Safari Online library and for $19.99 a month
can access up to ten titles from the O’Reilly list
of publications; this includes all the missing
manuals. With this subscription, you can have
your own library of ten titles, each of which is
available for browsing, cutting and pasting from,
and downloading for one month.
There is a 14-day free trial of this facility.
Perhaps inevitably (and depending on your
browser settings), the text is less easy to read in
this form. However, the figures are very effective
and accessible. Also, the facility lets you decide
which of the manuals on a particular software
package is the most appropriate for your level
and requirements.
29
Want to write one?
On the missing manuals website, you are invited
to write a manual for the series under the link,
‘Write for Us’. The publishers are looking for
writers who can write in the missing manuals
style — the ‘conversational, friendly approach,
clarity and a sense of what’s important in a
sentence, and in a piece of software’. They also
identify the need for the following:
Great patience (training experience an
advantage)
Reasonable speed (since computer books are
time-sensitive)
Technical expertise (experienced rather than
guru status, as a specific topic expert can assist).
With the supporting material of the Missing
Manuals Authors’ Guide and a sample chapter,
which is also provided on the website, the
publishers offer a serious invitation to would-be
contributors to write a chapter. The assignment
is to fully outline and partially write a chapter
of Microsoft Word: The Missing Manual (for
Windows or Mac). Details of the specific
chapter, its purpose and the formatting of the
material are given as part of the invitation. The
publishers offer to the successful author the
prospect of having fun while writing, and a high
probability of reaching the best-sellers’ lists!
What’s in it for ISTC members?
The continuing success of the missing manuals
series offers ISTC members the chance to:
Use the manuals; many of the titles will be
relevant
Follow David Pogue’s New York Times column
and check out his online tips
Use the The Missing Manuals Authors’ Guide; as
the checklist shows, many of the pointers can
be useful in our own document preparation
Contribute
to the series — with
the
prospect of
Inserzione2.ai
15-02-2006
9:06:31
fame, or at least fun. C
Current catalogue
 Access 2003 for Starters: The Missing Manual
 AppleScript: The Missing Manual
 AppleWorks 6: the Missing Manual
 Creating Web Sites: The Missing Manual
 Dreamweaver 8: The Missing Manual
 Dreamweaver MX 2004: The Missing Manual
 eBay: The Missing Manual
 Excel for Starters: The Missing Manual
 Excel: The Missing Manual
 FileMaker Pro 8: The Missing Manual
 FrontPage 2003: The Missing Manual
 GarageBand 2: The Missing Manual
 Google: The Missing Manual, Second Edn
 Home Networking: The Missing Manual
 iLife ‘05: The Missing Manual
 iMovie HD & iDVD 5: The Missing Manual
 iPhoto 5: The Missing Manual, Fourth Edn
 iWork ‘05: The Missing Manual
 Mac OS X Power Hound: Teach Yourself New Tricks,
Second Edn
 Mac OS X: The Missing Manual, Panther Edn
 Mac OS X: The Missing Manual, Tiger Ed
 Office 2001 for Macintosh: The Missing Manual
 Office 2004 for Macintosh: The Missing Manual
 Office X for Macintosh: The Missing Manual
 PCs: The Missing Manual
 Photoshop Elements 3: The Missing Manual
 Photoshop Elements 4: The Missing Manual
 QuickBooks 2005: The Missing Manual
 QuickBooks 2006: The Missing Manual
 Quicken 2006 for Starters: The Missing Manual
 Switching to the Mac: The Missing Manual, Tiger Edn
 Windows 2000 Pro: The Missing Manual
 Windows XP for Starters: The Missing Manual
 Windows XP Home Edn: The Missing Manual,
Second Edn
 Windows XP Power Hound: Teach Yourself New Tricks
 Windows XP Pro: The Missing Manual, Second Edn
Linda Robins FISTC
has worked in technical
communication for many
years, as editor, author,
manager and trainer. She
is one of the ISTC’s book
review managers.
E: review.manager@
istc.org.uk
Richard Truscott MISTC
has worked as a technical
author for ten years and
is the sole author at the
Sanger Institute.
E: rjt@sanger.ac.uk
QUALITY TRANSLATIONS INTO ITALIAN SINCE 1986
•
C
•
•
M
•
Y
CM
MY
•
•
•
CY
Technical translations: user manuals, product literature, catalogues and brochures
Corporate literature, patents, websites, financial, legal and promotional translations
Terminology and Translation Memory management with Trados and Star Transit
Desktop publishing (FrameMaker, Indesign, Quark Xpress, PageMaker etc.)
on Windows and Mac platforms
Software localisation
International project management
Professional in-house proofreaders and project managers
A member of EUATC
CMY
K
One of the first translation centres in Italy to be awarded Quality System certification to ISO 9001:2000 and Italian standard UNI 10574.
interlanguage s.r.l. - Strada Scaglia Est, 134 - 41100 Modena, Italy - Tel. +39 059 344720 Fax +39 059 344300
e-mail: info@interlanguage.it - www.interlanguage.it
30 Tools
Googling more effectively
Paul Beverley offers some tips on how to get the
most out of this popular search engine.
The trouble with Google is that, although you
know that the bit of information you want must
be in there somewhere, it’s not always easy to
bring it to the top of the pile. Thankfully the
Google engineers have provided lots of advanced
tools to help us — but that’s no good unless
we’re familiar with those tools. ‘RTFM!’, you say?
Well, yes, Google has provided us with lots of
documentation, but unless you know that there
are tools that are actually going to help you, you
aren’t going to invest the time in reading it.
(If you don’t know the meaning of RTFM, you
can always type define:rtfm into Google, and it
will enlighten you. And straightaway some of you
will have added a very useful Google tool to your
armoury — you can ask Google to define: anything.)
Figure 1. Entering a search term into Google
Anyone can be a learner
Obviously, in an article of this length, I can’t
reproduce Google’s manuals — there would be
no point. Rather, I shall give you a few ‘Did you
know?’ suggestions and hopefully, among all
the ‘Yes, I knew that’ responses there will be the
occasional ‘Oh, I didn’t know you could do that’, in
which case this article will have achieved its aim.
If you then decide to RTF(online)M and find even
more of Google’s hidden gems, that’ll be a bonus.
To make you feel more comfortable, let
me start with a confession. For years I used
Google and never once used the ‘I’m feeling
lucky’ button because I thought it would take
me to an on-line casino! In fact, it takes you to
the top result for your search. Try typing istc
communicator into the Google window and click
on the aforementioned button (Figure 1).
Using Google’s Advanced Search
Personally, I don’t! I find it a bit intimidating
and I’m never quite sure what it’s all about. In
any case, having learnt some of the shortcuts
and tricks that you can use from the keyboard, I
find it much quicker to just type things into the
normal Google command line.
Back to basics
Before going any further, let me just check that
you’re happy with a few of the basics. If I type
istc communicator into the Google window, I get
748 results, but if I use "istc communicator" — with
the quotation marks — I only get 47. Why? Well, the
latter search is asking for only those pages where
that exact phrase occurs, although the words can
be separated by punctuation. Without the quotes,
you’re just saying that the two words should occur
somewhere — anywhere — on the page.
Another useful way of making your search more
specific (for that’s what using Google is all about,
finding the specific piece of information you want)
is to use the minus sign — well, it’s the hyphen on
the keyboard, but it carries the idea of ‘take away’.
So, try looking up istc: a couple of million finds,
and most about a different ISTC. Try instead using
istc –student to eliminate some of the references
to the International Student Travel Confederation,
and the Institute’s website comes close to the top
of the list. Mind you, the number of finds is only
cut by half because there are an awful lot of ISTCs
in this world. (Actually, Google fails here. Using
define:istc only comes up with the Iron and
Steel Trades Confederation, whereas you get 46
different ISTCs from www.acronymfinder.com!)
Site: a powerful command
Second only to define:, I think that site: is my mostused command. So, for example, if I want information
on last year’s conference, I can use "conference
2005" site:istc.org.uk to get Google to look it
up for me. (If I can’t remember the URL for the ISTC
website, I can use "conference 2005" inurl:istc
to look for pages that contain the phrase ‘conference
2005’ on any website that has ‘istc’ in its URL.)
The usefulness of site: goes way beyond
searching specific websites. Suppose you want
to limit your search to UK websites. Well,
supposedly, clicking on ‘pages from the UK’ will
do that, but you still get American sites among
them. Adding site:uk to your search restricts the
search to only pages with .uk at the end of the
URL. And, of course, by the same token, you can
home in on, say, German websites with site:de.
Here are a few more suggested targets:
site:ac.uk
UK universities & colleges
site:gov.uk UK government
site:edu
US universities
site:mil
US military
site:gov
US government
University challenge
Searching UK university websites is easy with
site:ac.uk, but what about universities in other
31
countries? Well, you can do the same for certain
other countries such as Germany (edu.de) or
Belgium (ac.be). Unfortunately some countries
have chosen naming conventions that are not
hierarchical and so there’s no way of grouping
them. For example, French university websites are
of the form univ-rouen.fr (for the Université de
Rouen) and Italy has chosen names like unito.it
(for the Università di Torino) and uniba.it (for the
Università degli Studi di Bari). You can, in fact, get
at the French universities by using site:fr inurl:
univ. This works because the ‘univ’ in ‘univ-rouen’
counts as a ‘word’ within the URL. Unfortunately,
it doesn’t work for Italy because ‘unito’ and
‘uniba’ are separate and different words.
I’ve had success with Australia (edu.au), New
Zealand (ac.nz) and Poland (edu.pl), but others
such as Canada, Italy, Norway and Sweden seem
to have no name standardisation at all.
word. So, if I type in numoania, Google rightly asks
whether I mean pneumonia. But be careful: if you
type in diarea, Google will give you diarrhea (so to
speak!) which, of course, is the American spelling.
Another caveat here is that not all web pages spell
things correctly — for example, if I type in the
incorrectly spelt "neville shute", Google finds
803 pages. In this case, it would be worth trying
variations: "nevile shute" gives 102 pages and
"nevil shute" (the correct spelling) gives 44,100.
Quick tricks
Finally, here are some tricks you might find useful.
Phone numbers. If you have a phone number
and would like to know which part of the country
it represents, type in, say, 01633, and a quick flick
through the summaries of the web pages Google
finds will soon tell you that’s Newport (Gwent).
Postcodes. If you have an address and you’re not
sure which part of the country it’s in, type in the
Other facilities
first half of the postcode and you’ll soon find out.
Suppose you want to find an organisation’s
NR13? That’s Plumstead/Rackheath, near Norwich.
phone number, and suppose you’ve searched
ISBN numbers. Do you want to check an
and found the address of their website. You
ISBN number? Type 0718131797 into Google
then type site:acme.co.uk ~phone into Google.
and you’ll find it’s The Edge by Dick Francis,
The tilde (~) in front of ‘phone’ means ‘any
but if you get a digit wrong, you’ll know immed
word like...’, so it will find any pages on that
iately — 0718131787 did not match any documents.
organisation’s website that contain words like
Quotations. What if you want to check a
phone, telephone, call, calling or mobile.
quotation? Type in "picks up the * in the *
In my work with non-English authors writing
where her wedding has been" and the internet will
in English, I sometimes see names of people and
fill in the blanks. (Two of the pages seem to think
places that contain underline characters where a
the song is about someone called ‘Ella Marigby’!)
non-ASCII character has been lost in transmission
Bible references. If you want to know, for
(for example, Le_ajsk). So, how do I find the
example, what Acts 13:16 says, just type in Acts
missing letter? I simply guess what it might be
13:16 — it’s as simple as that.
and see what Google thinks. So, if I think that
Weights and measures. If you type 76 inches in
this Polish place name might be Lesajsk, I type
metres, it will tell you that it’s 1.93 metres. (Be careful
it into Google which rewards me with only 25
when using this for liquid measures — it assumes
finds, but it very helpfully says, ‘Did you mean:
gallons mean US gallons so you have to type,
Lezajsk’ (sic: no question mark!), but Lezajsk is
say, 35 litres in imperial gallons.) This function
is actually a calculator; I can type, say, 6.3*5+17*9.3
underlined as a link — click on it and I get 1.1
million finds, so that’s good enough for me.
and it will give me 189.6. I can even type 51 weeks
Lloyd_advert_2006_white.qxd
10:27
am Page 31 days 9 hours in seconds and it will tell me that
You can use this ‘ask the1/2/06
audience’
technique
when you can’t think how to spell a particular
it’s 31,136,400 seconds to my next birthday! C
Useful Help topics
www.google.co.uk/help/
operators.html
www.google.co.uk/help/
features.html
www.google.co.uk/
options/index.html
www.google.com/help/
calculator.html
Paul Beverley of Archive
Publications is a freelance
editor and proofreader
specialising in technical
material written by nonEnglish authors.
E: paul@archivepub.co.uk
W: www.archivepub.co.uk
Looking for a Technical Language Solution?
Lloyd International will help you:
Create effective localised versions of your software,
web presence and documentation
Improve your time to market
Reduce your localisation costs
Reflect the quality of your products across all languages
We’re talking your language - Call us today on
01829 730050
an ISO9001:2000 certified company
www.lloyd.co.uk
32 Methods
Soft documentation
Given the difficulty of providing up-to-date information for fast-moving
software products, Thomas Guest explores more effective toolchains.
Introduction
I am a member of a small team of software
developers working on a novel software product (I’ll
call it ‘the Product’ from now on). Recently I spent
some time working on the user manual, which
was based on a Microsoft Word master document.
From this master, various output formats were
generated in a semi-automated fashion.
Word is a popular and powerful tool. It does
have its drawbacks though, especially for technical
documentation, and these were amplified by the other
tools involved in producing the final deliverables.
We’ll look more closely at the drawbacks later. I
summarise them here by saying the proprietary
tools and file formats led to a loss of control.
Setting up collections of tools (toolchains) to
produce technical documentation in multiple
formats is a difficult problem, but also one that has
been solved many times over. Plenty of open-source
projects provide model solutions. My increasing
frustration with the Word-based toolchain led me to
explore one of these alternatives. This article records
the outcome and tells how, in the end, we regained
control over the user manual, but at a price.
Requirements
The requirements for the manual were clear.
It had to fit the corporate style, which dictated
various presentational aspects, and there would
be pictures, screenshots and cross-references.
Naturally, the contents would provide clear and
complete details on how to use the Product. We
needed just two output formats:
1. Hardcopy, printed and bound
2. Linked online web pages.
Of course, the two versions must agree with each
other. The Product, a server-based piece of software
with a browser interface, should integrate with the
online documentation in a context-sensitive manner:
clicking the Help icon next to a user interface (UI) item
should open the manual at the appropriate point.
The last requirement was slightly strange: the
documentation should be substantial. Somehow, it
seemed unreasonable to ask customers to pay lots
of money for a CD of software; bundling in a weighty
manual made the final deliverables more tangible.
This, to me, is a suspect requirement, and one we
should keep in check, or we risk producing docu
ments containing many cut-and-pasted sections.
Credits
My thanks to the editorial
teams at both Overload
and Communicator
for their help with this
article. Overload is an
ACCU journal.
The existing documentation toolchain
With the existing toolchain based on a Word
document, producing hardcopy was a simple
matter of printing and binding. The output
looked pretty much as previewed: the author had
good control over pagination and positioning.
Linked web pages took more effort. With a tool
that I’ll call Word Doctor (not its real name because
I’m going to moan about it), generation involved:
Creating a new Project
Pointing it at the Word document
Selecting project options in Word Doctor
Clicking the build button.
Making a cup of tea while the pages generate.
All fairly easy — in theory. In practice, steps the Word
Doctor user manual neglected to mention were:
Exit Word. Word Doctor had trouble accessing
the document otherwise.
Restart the PC. For some reason, a resource
became terminally locked up.
Rewrite the Word document using the Word
Doctor document template.
Don't forget to exit Word!
Create a new project as above.
Click the build button.
Click away a few warnings.
Read the Word Doctor workarounds Wiki page
on the intranet.
Click the build button again.
Go for lunch. Builds took around half an hour.
I am not exaggerating. The engineering manager
admitted that he estimated it took at least two days
of struggling to convert a Word document into the
online form. The final irritation was with the output.
The HTML was packed with Internet Explorer specific
Javascript, and looked poor in any other browser.
Connecting to Word Doctor output
The real downside of Word Doctor was when it
came to trying to connect the Product to the web
pages. It was a multi-layered integration task:
I worked with the technical author to ensure the
content was accurate and complete.
The Product’s web-based UI called for help using
a text identifier. The Help subsystem used the
identifier to look up an HTML location — a page
and an anchor within it — and then displayed a
new window containing this location.
I configured Word Doctor to ensure that its
HTML output included the right locations.
Unfortunately, there were problems with each of
these layers. I got on well with the technical author
but the documentation tools made it hard for us
to work on the same file. We had to take turns or
work on copies. I couldn’t even fix a typo directly.
Word Doctor produced a frame-based collection
of static HTML pages. Limitations of frames make
external references to a particular location tricky, so
the Product’s help subsystem had to generate a framed
front page displaying the appropriate left and right pane
dynamically each time it was called. Not too difficult
perhaps, but more complex than strictly necessary.
33
Pages and anchors were both moving targets in
the Word Doctor output. Adding a new section to
the document risked breaking the help references.
The technical author wanted the Product to
stabilise to be able to document it; I needed the
documentation to stabilise to be able to link to it.
Other problems
Word uses a proprietary binary format. This ties you
into the product to a degree; effectively, you rely on
Microsoft to look after your data because you cannot
work with it without Word. You may be able to live
with the risk of Microsoft collapsing during the life
of your document but you are also vulnerable to the
company ceasing to support the version of Word
you prefer, or charging an unreasonable amount for
an upgrade. It also means:
It's hard for more than one person to work on
a document at a time, as changes to binary files
cannot easily be merged.
Revision control becomes more expensive
and less useful (how do you view differences
between two versions of the manual?)
It is difficult to automate anything. As a trivial
example, Word Doctor has no batch interface
and requires human input at every stage.
Consider trying to re-badge the manual if the
Product is distributed by a partner company.
With a decent documentation toolchain, this
should be as simple as the build ‘prepare’ target
copying the correct logo graphic into place and
applying a transformation to some text strings.
Resistance to change
Despite all of these limitations and irritations it
was hard to convince anyone that a procedural
change was necessary or even desirable. The
reasons were as much organisational as technical:
The existing tools had been used to produce
acceptable end-user documentation in the past
for other products shipped by the company.
Already, considerable effort had been put into
the Word document for the Product (even if
much of it would have to be scrapped due to the
inevitable changes as the Product developed).
Setting up a smarter toolchain required engi
neering input; would the technical author be
able to use the new tools productively?
I could (and did) argue against all of these points:
Previous documentation was standalone: it did
not have to integrate with what it documented.
Using existing tools to connect the Product with
its documentation would be a continual effort.
I had every confidence that the technical author
could quickly master a new documentation
tool, and that such a tool would save us all
time, even in the short term.
As I saw it, we risked treating documentation as an
add-on — a nice-to-have — rather than as an integral
part of the Product, and I believe this is wrong. Decent
documentation is one of the first things I look for when
I evaluate a piece of software. Quite simply, I didn’t
want to deliver a Product with poor documentation.
Regaining control
My frustration with the existing tools set me
thinking about alternatives. I looked first to the
open-source world, where there’s no shortage
of excellent documentation and where authors
are happy to show how they generated it. I
experimented by downloading and trying to build
some open-source documentation. Could I change
fonts, include images, replicate the house style? How
easy were the tools to use with our own content?
After an afternoon’s experimentation, I had
something worth showing to the engineering
manager: an end-to-end solution that, from a
DocBook XML master, generated a skeleton PDF
and HTML user manual in something approaching
the house style. I suggested that we should use the
tools I had demonstrated for the user manual. I
said I’d be happy set up the toolchain. The manager
agreed with me that, technically, it seemed the way
forward. However, it wasn’t easy for him to give me
the go-ahead for the reasons I have discussed.
I confess that I had my own doubts too. All I
knew at this stage was that DocBook could do
the job and that I would happily tinker with it to
get it working for us. I didn’t know if we could be
productive using it, but at least we understood the
limitations of the current tools. We both recognised
that the single most important thing was content.
Full and accurate documentation supplied as a
plain README would be of more practical use
to our customers than something beautifully
formatted and structured but inaccurate.
In the end we deferred making a final decision
on what to do with the user manual. However, the
results of my experiment did seem worth recording,
so I spent a day or so tidying up and checking in the
code so we could return to it, if required.
A DocBook toolchain
I should outline here the basics of the toolchain I
evaluated, which was based on DocBook. A twosentence introduction to DocBook can be found on
the front page of the SourceForge DocBook Project:
‘DocBook is an XML vocabulary that lets you create
documents in a presentation-neutral form that
captures the logical structure of your content.
Using free tools along with the DocBook XSL
stylesheets, you can publish your content as HTML
pages and PDF files, and in many other formats.’
I’d also like to highlight some points from the
preface to Bob Stayton’s DocBook XSL: The Complete
Guide — a reference that DocBook user is sure to have
bookmarked: ‘A major advantage of DocBook is the
availability of DocBook tools from many sources, not
just from a single vendor of a proprietary file format.
You can mix and match components for editing,
typesetting, version control, and HTML conversion.
… The other major advantage of DocBook is the set
of free stylesheets that are available for it. … These
stylesheets enable anyone to publish their DocBook
content in print and HTML. An active community of
users and contributors keeps up the development
of the stylesheets and answers questions.’
Version control
Software must adapt to survive.
Features are added, bugs squashed;
maybe the UI gets a makeover, maybe
configuration files are replaced by a
database. Customers do not usually
get exposed to this state of flux.
Typically, they receive stable and
tested versions, though they may
also expect to receive patches, for
example, to fix critical bugs.
Software developers rely on
version control systems to keep track
of changes made to files: when the
change was made, who made it, and
which versions of the software it should
be applied to. Computers are good at
isolating differences between revisions
of a source file and at copying these
differences between versions of a code
base. Thus, a programmer can (for
example) fix a bug once, and the version
control system can then be used to
safely patch the fix wherever it’s needed.
In a large code base, the version
control system can be configured to
enable a team of programmers to work
on the same set of files, and even on the
same file. The version control system can
make sense of concurrent modifications,
and merge them accurately; and, in the
rare situations it can’t, it fails safely.
These considerations apply equally
to the user manual, versions of which
must map to versions of the software.
By choosing suitable documentation
formats and adopting version control,
authors can realise the same benefits.
In fact, the leading open-source
version control system, Subversion,
explains the concept of branching a
project using the particular example
of a document — a handbook, in this
case. For more information, see http://
svnbook.red-bean.com/en/1.1/ch04.
html#svn-ch-4-sect-1. Note also
that the Subversion documentation is
written in DocBook.
34 Methods
Soft documentation
As a user, I expect software to just
work, especially when it has a
graphical UI. It should be obvious
what I need to do without reading
a manual or waiting for tooltips
to float into view. By designing a
graphical UI that operates within a web
browser, we have a head start: there’s
no need to document how hyperlinks
work or what the address bar is for.
What’s more, the Manifesto for Agile
Software Development explicitly prefers:
‘Working software over comprehensive
documentation’.
These considerations don’t mean
the manual is redundant or unwanted,
though. We don’t want to clutter the
UI with reference details. There remain
occasions when hardcopy is invaluable.
What’s more, when you try to design
an intuitive UI, you realise that the
distinction between software and
documentation is somewhat artificial:
it’s not so much that the boundaries
blur as that, from a user’s point of view,
they aren’t really there. Suppose, for
example, that a form requires an e‑mail
address to be entered. If the user enters
an invalid address, the form is redrawn
with the erroneous input highlighted
and a message displayed: ‘Please enter
a valid e‑mail address’; there is also a
clickable Help icon directing users to the
relevant page of the user manual. Which
of these elements of the UI are software
and which are documentation?
Suppose we are delivering a library
to be linked into a larger program. The
documentation is primarily the header
files that define the interface to the
library. We must invest considerable
effort making sure these files define a
coherent and comprehensible interface:
maybe we deliver the library with
example code and makefiles (files that
specify how the system is built); maybe
we provide a test harness; maybe we
generate hyperlinked documentation
directly from the source files; maybe
we supply the library implementation
as source code. Which is software and
which is documentation?
Software developers should
remember that ‘Programs should be
written for people to read, and only
incidentally for machines to execute’
(Abelson and Sussman). In other words,
software is documentation. Software
should be soft — soft enough to adapt
to changing requirements. We must be
sure to keep our documentation soft too.
So, the master document is written in XML
conforming to the DocBook DTD. It provides
the structure and content of our document.
Transforming it into different output formats
starts with the DocBook XSL stylesheets. Various
aspects of the transformation can be controlled by
setting parameters to be applied (do we want a date
stamp to appear in the page footer?, should a list of
figures be included in the contents?), or by writing
custom XSL templates (for the front page, perhaps).
Depending on the exact output format, we may
still have work to do. For HTML pages, the XSL
transformation produces nicely structured HTML,
but we probably want to adjust the cascading style
sheet and perhaps provide our own admonition
and navigation graphics. For Windows HTML
Help, the DocBook XSL stylesheets again produce
a special form of HTML, which we must then run
through an HTML Help compiler.
PDF output is rather more fiddly: The DocBook
XSL stylesheets yield XSL formatting objects from
the DocBook XML master. Further processing is
required to convert these objects into PDF. I used
the Apache Formatting Objects Processor (FOP),
which in turn depends on third-party libraries for
image processing and so on.
As we can see, there are choices at all stages.
At first, these choices were a distraction. I wanted
the most direct route to generating decent docu
mentation. I kept reminding myself that content
was more important than style (even though the
styling tools were more fun to play with).
The technical author departs
We continued on, then, deferring work on the
documentation until at least we had frozen the
UI. Then the technical author left (she had landed
a full-time editing position on a magazine). Again,
I volunteered to work on the documentation. By
now the engineering manager had succeeded
in selling to higher management the idea of
switching documentation tools.
Version 1.0 was due to be released in two
weeks. We had four choices:
Ship with the existing documentation, which
was dangerously out of date.
Stub out the documentation entirely, so at least
users wouldn't be misled by it.
Revise the Word document, use Word Doctor to
generate HTML, reconnect the HTML to the Product.
Rewrite the manual using DocBook.
We ruled out the first choice even though it required
the least effort. The second seemed like an admission
of defeat: could we seriously consider releasing a
formal version of the Product without documentation?
No one present had any enthusiasm for the third
choice. So, finally, with less than a fortnight until
code-freeze, I was assigned the task of finishing
the documentation using the tools of my choosing.
Problems with DocBook
Most things went rather surprisingly well, but I
did encounter a small number of hitches.
Portability
My first unpleasant surprise with the DocBook
toolchain came when I tried to generate the
printable PDF output on a Windows XP machine.
Rather naively, perhaps, I’d assumed that since
all the tools were Java-based I’d be able to run
them on any platform with a JVM. Not so.
The first time I tried a Windows build, I got a
two-page traceback triggered by an exception
raised in one of the graphics processing libraries.
Fortunately, I was able to work around the problem
by swapping the graphics library for an alternative
version, apparently with no adverse effects.
The incident did shake my confidence, though.
It may well be true that open-source tools give
you the ultimate level of control, but you don’t
usually want to exercise it! At this stage I had
only tried building small documents with a few
images. I remained fearful that similar problems
might recur when the user manual grew larger
and more laden with screenshots.
Volatility
We all know that healthy software tools are in
active development, but this does have a downside.
Some problems actually arose from the progression
of the tools I was using. For example, I started out
with the version of the DocBook XSL stylesheets
I scavenged from my reference open-source
documentation build (version 1.65.1). These were
more than good enough for my needs, but much of
the DocBook documentation I was using referred
to more recent distributions. In this case, switching
to the most recent stable distribution of the XSL
stylesheets resulted in improvements all round.
Apache FOP is less mature though: the last stable
version (as of December 2005) is 0.20.5 — hardly
a version number to inspire confidence — and
the latest release, 0.90 alpha 1, represents a break
from the past. I anticipate problems if and when I
migrate to a modern version FOP, though again, I
also hope for improvements.
Verbosity
XML is verbose and DocBook XML is no exception.
As an illustration, here is a section of a DocBook
document:
<para>
We needed just two output formats:
</para>
<itemizedlist>
<listitem>
hardcopy, printed and bound
</listitem>
<listitem>
linked online web pages.
</listitem>
</itemizedlist>
XML claims to be human-readable, and on one
level, it is. On another level, though, the clunky
angle brackets (chevrons) and obtrusive tags make
the actual text content in the master document
hard to read: the syntax obscures the semantics.
35
Control
The DocBook toolchain gave us superb control
over some aspects of the documentation task. In
other areas the controls existed but were tricky to
locate and operate.
For example, controlling the chunking of the HTML
output was straightforward and could all be done
using build-time parameters, with no modifications
needed to the document source. Similarly,
controlling file and anchor names in the generated
HTML was easy, which meant that the integration
between the Product and the online version of the
user manual was both stable and clean.
Some of the printed output options don’t seem
so simple, especially for someone without a
background in printing. In particular, I still haven’t
got to grips with fine control of page-breaking
logic, and have to hope no one minds too much
about tables that split awkwardly over pages.
The rush to completion
In the end, though, all went better than we could
have hoped. I soon had the documentation
build integrated with the Product build. Now the
distributable ISO CD image had the right version
of the user manual automatically included. I wrote
a simple program to check the integration between
the Product and the user manual. This program
checked that the various page/anchor targets
that the Product used to launch the pop-up Help
window were valid. This script too became part of
the build. It provided a rudimentary safety net as I
rolled in more and more content.
Next, I cannibalised the good bits of the existing
user manual. We knew what problems we had
seen in the field: some could be fixed using better
examples in the Help text; I fixed these next.
Within a couple of days the new manual had all
the good content from the old manual and none of
the misleading or inaccurate content; it included
some new sections and was fully linked to the
Product. It was, though, very light on screenshots.
QuickBook
I had a workaround for the verbosity issue. I used
QuickBook, one of the Boost tools. QuickBook is a
lightweight C++ program that generates DocBook
XML from a WikiWiki style source document. Using
QuickBook, we can write our previous example as:
We needed just two output formats:
1. Hardcopy, printed and bound
2. Linked online web pages.
QuickBook documents are easy to read and
easy to write. QuickBook does, however, fall a
long way short of the full expressive richness of
DocBook but if all you need are sections, crossreferences, tables, lists, embedded images and so
on, then it’s ideal.
Screen captures
In an ideal world we could programmatically:
Launch the Product
Load some data
Pose the UI for a number of screenshots
Capture these screenshots for inclusion in the
documentation.
Then this program too could become part of the
build and, in theory, the screenshots would never
fall out of step with the Product. Already we had
some tools in place to automate data loading and
to exercise the UI. We still have no solution for
automatically capturing and cropping the images,
so we rely on human intervention. So far, this
hasn’t been a huge issue.
Build times
It wasn’t going to be hard to beat Word Doctor
on build times. Currently, it takes about a minute
to generate the full user manual, in both PDF and
HTML formats, from source. A simple version
check means that the documentation is only
generated when required. The real gain here is
not so much that the build is quick, but that it is
automatic: not a single button needs clicking.
Conclusions
The real benefits of the new documentation
toolchain are becoming more and more apparent.
As a simple example, a single text file defines
the Product’s four-part version number. The
build system processes this file to make sure
the correct version number appears where it’s
needed: in the UI, in the CD install script — and,
of course, in the documentation.
Another example. If we receive a support
call that we think could have been avoided had
the documentation been better, then we fix the
documentation directly. Anyone with access to the
version control system and a text editor can make
the fix. The full printed and online documentation
will be regenerated when they next do a build, and
will automatically be included in the next release.
And a final example. The Product I work on
performs checks on file-based digital video, and
the range and depth of these checks is perhaps
the area that changes most frequently. The
architecture we have in place means that these
low-level enhancements disrupt the higher levels
of the software only minimally: in fact, the UI for
this part of the Product is dynamically generated
from a formal description of the checks that are
supported. Adding a check at this level is a simple
matter of extending this formal description.
We also need to document the check: perhaps
a reference to the video standard and a precise
definition of the metrics used. With an intelligent
documentation toolchain the documentation can
live alongside the formal description and build-time
checks confirm that the help text links up properly.
From an engineering point of view, document
ation is properly integrated into the Product. I
finish with another quotation from Stayton:
‘Setting up a DocBook system will take some time
and effort. But the payoff will be an efficient,
flexible, and inexpensive publishing system that
can grow with your needs.’ C
References
Abelson and Sussman,
Structure and Interpretation
of Computer Programs,
Harold Abelson, Gerald
Jay Sussman with Julie
Sussman MIT Press, 1984;
ISBN 0-262-01077-1
Apache FOP http://
xmlgraphics.apache.org/fop
Boost www.boost.org
Boost QuickBook www.
boost.org/tools/quickbook
DocBook
http://docbook.org
Manifesto for Agile
Software Development
http://agilemanifesto.org
Word http://office.
microsoft.com
Stayton DocBook XSL: The
Complete Guide
www.sagehill.net/
docbookxsl/index.html
Subversion http://
subversion.tigris.org
The DocBook Project
http://docbook.
sourceforge.net
Thomas Guest is
an enthusiastic and
experienced software
developer. During the past
20 years, he has played
a part in all stages of the
software (and indeed
product) development
life cycle. He is an active
member of the ACCU
(http://accu.org).
E: thomas.guest@
gmail.com
W: www.wordaligned.org
36 Careers
Bombproof your CV!
A seemingly pristine CV might be mangled once it leaves your hands.
David Cooper suggests some remedies.
Shauna Kelly’s articles
‘Why does text change
format when I copy it into
another document?’
www.shaunakelly.com/
word/styles/FormatOf
TextChanges.html
‘What happens when I
send my document to
someone else? Will Word
mess up my formatting?’
www.shaunakelly.com/
word/sharing/WillMy
FormatChange.html
During two rounds of recruitment for a contract
technical author, I looked at about 30 curricula
vitae. Sadly, they made depressing reading:
far too many candidates could be immediately
eliminated because of avoidable errors.
Whereas a Java programmer might be forgiven
for having, say, a few spelling mistakes in his or
her CV, as technical communicators, our CVs are
a good showcase for the quality of our work. If
someone hasn’t taken care over their own CV,
it’s fair to assume that they’d take even less over
their client’s documentation. So in the hope that
Communicator readers can avoid these traps
and get at least as far as the interview, I offer
some suggestions.
However, I won’t be discussing the structure
of CVs much as this is widely covered elsewhere.
One ISTC member I know consults a CV advice
firm every few years to check the current trends;
he believes the £50 or so charged is a modest and
worthwhile investment. Or you might get some
pointers for free from a friendly agency. Issues
of Communicator that have featured CVs include
Spring 2006, Autumn 2005, Spring 2004 and
Winter 2002. Most of the CVs I looked at were in
the standard structure: name, profile, skills and
achievements, career history in most-recent-first
order, education, and perhaps hobbies.
I will be mentioning Microsoft Word’s features.
This is simply because it is the de facto standard
used by agencies. I know from the ISTC’s e‑mail
groups that some members would cheerfully
renounce Bill Gates and all his works, particularly
Word. However, much as you might prefer
OpenOffice.org Writer or some such, there will
inevitably be the stage where either you, or the
agent, must convert your CV into Word format.
I suggest that you keep control of this stage,
as it is just another point where errors can be
introduced. If you do not have Word but do have
Windows, you can download a free Word Viewer.
Better still, get the use of a PC where Word is
installed and finish your CV there.
The abbreviated instructions I shall give are
correct for Word 2003; in earlier versions, the
instructions might vary slightly.
Agency pitfalls
The agencies sending me the CVs were all general
IT agencies. You can expect that the dozen or so
specialist documentation agencies will take more
care with your CV and many of the following
comments will not apply to them. Indeed, some
make it a selling point that they will treat your CV
carefully. Remember, though, that many potential
clients have preferred supplier agreements with
a small range of agencies and will not normally
recruit through a specialist.
Your CV might look pristine on your own
computer, but the agency might inadvertently
introduce errors that you usually never get to see.
(When interviewing, I gave each candidate a copy
of their CV as presented by the agency, so they
could see how the agency might have affected it.)
The man or woman at the agency is often paid
largely by commission and is always in a rush
to get your CV to the client before the rivals do.
If two agencies send your CV to the same client
(as sometimes can happen, despite your best
efforts), the client will nearly always deal with the
agent who sent it first. Such clashes are rare, but
nonetheless an agency still wants its candidates’
CVs to arrive in the client’s Inbox first.
Once you’ve agreed that your CV should go
forward, an agent will typically:
1. Copy your entire CV and paste it into a new
document based on the agency’s template.
2. Remove your address and other contact
details.
3. Fill in the ‘cover sheet’ page. This will vary
slightly between agencies, but will always
include your name, availability, desired rate,
and the agency’s margin.
4. E‑mail it to the client.
The agent generally won’t check the CV before
e‑mailing and changes at this stage often go
unnoticed. While a few clients might guess that
some faults in your CV lie with the agency, most
will not — so why take a risk?
Styles
Standard Word styles such as Bulleted, Heading 2,
and Normal are a problem. In your own CV based
on your template, these will naturally work in
harmony. However, when the agency pastes your
text into their document, the styles will typically
adopt whatever is set in their template. So their
Normal might be 12-point Garamond indented at
2cm while their Bullets could be 9-point Arial with
no indent. In an instant, your CV looks a mess.
Avoid the standard Word styles and instead
create your own ones with unique names (for
example, by using your initials). When creating a
style, select (no style) from the Style based on list,
which will make the style more robust. Similarly,
base your CV on a uniquely named template
rather than Normal.dot. For further safety, choose
Tools > Templates and Add-Ins and, in the
Templates tab, ensure that the Automatically
Update Document Styles checkbox is cleared.
For more on why format changes on different
machines, see Shauna Kelly’s articles (left).
37
Page layout
Page layout is another problem area. The agency’s
template might have wildly different page margins
from your own — perhaps with a logo and contact
details in the headers and three paragraphs of
impeccable legalese in huge footers. So page breaks
that work perfectly in your version of the CV might
be nonsensical in another. What the client might
see is a mysterious white space in the middle of
the page because the author effected a page break
with a series of paragraph marks. The client might
also see the text finish halfway down a page where
the next page was started by using a manual page
break or by associating one with a paragraph.
To avoid such gaffes, dispense with page
breaks altogether. When setting up a style such
as a heading, then to keep it on the same page as
the text it precedes, use Keep with next. (Choose
Format > Paragraph > Line and Page Breaks and
set the Keep with next paragraph checkbox.)
For all styles, to stop a paragraph from splitting
across two pages, set the Keep lines together
checkbox (in that same Line and Page Breaks tab).
Spacing between paragraphs should be set on
the adjacent Indents and Spacing tab. (Consider
what the reader will see after clicking the Show/
Hide button: if empty paragraphs are used for
formatting, this suggests a limited grasp of Word.)
Different left and right margins are also a
problem. I tend to put my ‘from’ and ‘to’ dates at
the end of the ‘company’ line, using a right tab.
But if the agency’s page margins are different,
these lines will either look too wide or too narrow.
As I’ve developed this article, I moved towards
thinking that the most robust approach is to put
the majority of the text within tables. To stop rows
from being split, select the whole table and choose
Table > Table Properties > Row and clear the Allow
row to break across pages checkbox. To keep a
row on the same page as the one it precedes, select
it and use Keep with next as described previously.
Text in a cell can be right-justified without the
need for tabs. An added advantage of tables is that
you can largely control row heights and column
widths. The disadvantage is that, regardless of any
decisions you may have made about cell borders,
the gridlines are visible online, which might
give your CV a cluttered appearance (unless the
reader has chosen Table > Hide Gridlines).
Proofreading
In my sample, 90% of the CVs simply hadn’t been
proofread properly, which led to their rejection.
Some problem areas are discussed next.
Spelling. Many spelling mistakes were
undetected by the CV’s author because a style
was set to US English. When you set up a style,
ensure it is set to UK English or whatever is the
language appropriate for your target market. If
a product or organisation name uses a foreign
spelling such as ‘center’ set that particular word
to its correct language: that’s one less red wiggly
underline for the client to see. Spellcheckers are,
of course, no guarantee of weeding out errors:
the world is full of ‘principle’ technical authors.
Product names. Your claims to expertise in a
particular product are undermined if you don’t give
its correct name: one CV I saw even managed to get
the name of Internet Explorer wrong. The fondness
of manufacturers for medial capitals causes no
end of problems: in another CV, a graphics tool
was spelt variously as PaintShopPro, Paintshop
Pro, and Paint Shop-pro. If you’re unsure of a tool’s
correct name, choose About from its Help menu.
If you no longer have access to the tool, find the
manufacturer’s website and follow their style.
Organisation names. Similarly, if you can’t
spell a former client’s name correctly (as one
candidate failed to do) this fuels scepticism.
Style. Make sure you are consistent: for
example, ‘online’ and ‘on-line’ are both perfectly
acceptable forms, but not in the same document.
In the same manner, if you like to capitalise
phrases such as ‘Online Help’, do so consistently.
Different formats for the date ranges of your
previous engagements are another common
pitfall: choose a format and stick to it.
Obsolescence. If you’re in a hurry to move to
your next role, the temptation is to insert the
details of your most recent assignment near the
front to your CV and dash it off to the agencies.
That way, errors creep in. For example, one
candidate wrote, ‘I have four years’ experience’,
when actually he had seven. Look for such
statements, and recast them into a form that won’t
age, such as, ‘I have been an author since 1999’.
Before you send off your CV, transfer it
to a different PC and print it out; this might
reveal formatting changes and errors, such
as unresolved fields, that you would not see
on your own machine. Proofreading your own
work is never easy; some errors in my own CV
were there for years before I spotted them and
I introduced at least one with my latest update.
Ask a colleague to proofread it for you. If no-one
with the right skills is to hand, ISTC members
could try asking other members through the
IASIG or Discussion e‑mail groups.
Microsoft articles
‘How to obtain the latest
Microsoft Word Viewer’
[Article ID: 891090]
http://support.microsoft.
com/kb/891090/en-us
‘The Remove Hidden
Data tool for Office 2003
and Office XP’ [Article
ID: 834427] http://
support.microsoft.com/
kb/834427/en-us
‘Fonts and products’
www.microsoft.com/
typography/fonts/
default.aspx
Length
People argue about the ideal maximum length
of a CV: some say no more than two pages;
most would say four. Some candidates offered
six- and eight-page CVs, but all of these could
have been shortened with some firm editing
and simple layout changes. If you’ve had a
long career or for some other reason think you
might need to present a magnum opus at some
stage, I’d suggest two CVs: a shorter one with
the emphasis on your most recent work, which
refers to a longer one that’s available on request.
Repetition
One doesn’t have to be a total believer in
minimalist documentation to think that repetition
should be reduced, but many CVs failed on that
38 Careers
References
Lockwood, Brett (2003)
‘Understanding Font
Substitution in Word’
Part 1: www.melbpc.
org.au/pcupdate/2310/
2310article10.htm
Part2: www.melbpc.
org.au/pcupdate/2311/
2311article9.htm
Wyatt, Allen ‘Font
Substitution Problems’
http://wordtips.vitalnews.
com/Pages/T1167_Font_
Substitution_Problems.
html
David Cooper MISTC has
been a freelance technical
author since 1994. He
has served on the ISTC
Council and as the ISTC
Newsletter Editor.
E: DavidCooperMISTC
@yahoo.co.uk
score. One man memorably sought to show that
his periods of ‘resting’ were being spent fruitfully
by writing a novel. Given the usual obsession with
gaps in CVs, who can blame him? But this entry
went on for a quarter of a page, giving details of
the book’s title, setting, plot outline and so forth.
Upon turning the page, the self-same information
was repeated to explain an earlier gap.
A common source of repetition is software.
Some candidates rather obsessively list every
bit of software used at every client, for example,
starting with Word 2003 at their latest client,
going through all the earlier versions as they went
back through their career and ending up with the
WordPerfect 5.1 for DOS of their youth. Software
expertise is best summarised in the skills section
of your CV though, if work at some client involved
a particularly interesting combination of software,
there might be a case for keeping it there too.
There is some tension between brevity and
ensuring that you are found in agency keyword
searches. If your CV says, ‘FrameMaker 7.2 and
previous versions’, you’ll be found by a search
on ‘FrameMaker’ but not by one on ‘FrameMaker
7.0’. If this is a worry for you, keep your CV in a
more verbose form. In summary, review your CV
as a whole and trim all the surplus fat.
Fact checking
Let’s assume you’ve overcome the first few
hurdles and the client is now looking at your
CV in detail. It really is much easier these days
for clients to check facts. Among the CVs I
reviewed were claims of membership of fictitious
organisations and false claims of membership
of real ones. Follow-up enquiries yielded some
amusing answers. One man, who bogusly claimed
to be an ISTC member, produced an elaborate
excuse of the ‘dog ate my membership card’
variety. Naturally, he wasn’t shortlisted.
Make it easy to check your CV. If you’re an ISTC
member, get listed in the Directory of Members
at www.istc.org.uk/pages/members/memberslist.
php and put the link in your CV. Ensure that
your previous clients are checkable too. One
idea I’ve borrowed is to put hyperlinks in the CV
(these are written in full so that they are readable
in a printed copy). If the reader is particularly
interested in a former client, he or she can visit
that organisation’s home page; this reduces the
need to describe the client beyond a sentence.
It also helps safeguard your CV against the
obsolescence mentioned earlier. A previous client
might change its name, be taken over, or cease
trading altogether. By checking their URLs before
you distribute each CV update, you can track such
developments and amend the CV accordingly.
If you can’t track down a former client,
the Companies House WebCHeck service at
WebCHeck service http://wck2.companieshouse.
gov.uk enables you to search for UK companies
by previous names or dissolved names.
The names of client’s products also change;
what you once documented as AcmeWrite might
now be SnibboScribe. Get the up-to-date name
into your CV so it can be found in searches. The
organisation’s press release archive on its website
is a good place to look. If you have no joy, ring
your old client and ask; it might take some time
but eventually you’ll find someone who knows.
They’re out to get you…
Your Word settings may differ from those of the
reader and you might send more information than
intended. Problem areas include tracked changes,
versions, hidden text and comments. The Word Help
topic ‘Remove personal or hidden information’ is
informative. The cautious can download the free
Remove Hidden Data add-in or look at the Privacy
Options in Tools > Options > Security. These
will come in handy for all sorts of documents, of
course, some almost as important as your CV.
Format for online reading
Some years ago, the client first read your CV on
paper, but nowadays they probably skim it first
online after opening the attachment in the agent’s
e‑mail. If impressed, they will print it later for
more detailed scrutiny. Many of the CVs I looked
at were still firmly in the early 1990s, using
default fonts, such as Times New Roman, and
small point sizes that performed poorly on screen.
Choose fonts that are serviceable both on screen
and on paper. Serif fonts include Bookman Old
Style, most of the Century family, and Georgia; sans
serif ones include Arial, Trebuchet, and Verdana.
Changing a style’s font might necessitate an
adjustment to its size as well, to allow for different
x‑heights: after changing 12 point Times New
Roman to Verdana, you would want reduce the size
by 1 or 2 points. Experiment with copies of your CV
until you arrive at something pleasing to the eye.
Avoid uncommon fonts, which might be
substituted; for example, Lucida Bright might
be substituted by Georgia on the client’s PC
(Lockwood). The Microsoft ‘Fonts and products’
page is a useful guide to the fonts supplied with
various products and operating systems but, of
course, you can only guess what the client has
installed. If you are wedded to an obscure font and
it is a TrueType font, you can embed it (Wyatt).
If you use online job-hunting services that convert
your CV into various formats, check its appearance
in all of them. Among other things, you might
find that uncommon characters are converted
into nonsense ones. An example is Jobsite, which
converts a CV into plain text and HTML and prefixes
the Word version with its own text.
And finally…
I’ve listed some of the more important issues I’ve
come across, but I’m sure there are many more to
be found. If you’ve come across any pitfalls to
avoid, or have any tips to follow, please e‑mail
letters@istc.org.uk and we’ll put together a digest
for a future issue of Communicator. C
39
Tools
Mastering master pages: part 1 of 2
FrameMaker’s master pages enable you to control the layout of your
document’s pages — and more. Steve Rickaby looks at the options.
Even if you are a novice user of FrameMaker, you
will have used master pages, although you may
not have realised it. FrameMaker uses master
pages to control the page layout of every page of
a document or book.
Jane Dards touched on master pages in
the context of side-heads in her article ‘A
Bit on the Side’ in the Summer 2005 issue of
Communicator. This, the first of two articles,
gives a general overview of master pages and
their various options, then describes how they
can be applied automatically. The second article
will consider some slightly more exciting ways
of using master pages.
Some aspects of master pages can seem
complex and confusing, but correctly applied, they
can make your work with FrameMaker a lot more
productive and enjoyable. As a simple example,
it is easy to make FrameMaker format the first
page of each chapter of a book differently.
Two types of document
One way of looking at the use of master pages is
mentally to divide documents into two broad groups:
Book- or report-style publications, in which
most pages follow similar layouts.
Newsletter- or magazine-style publications, in
which many (or all) pages have different layouts.
These two document groups have very different
layout requirements, irrespective of how they
are ultimately delivered to their consumers.
FrameMaker caters for both.
Displaying and working on master pages
Figure 1. The Custom Blank Paper dialog
Figure 2. Master page view (truncated)
When you create a new document by selecting
File>New Document, FrameMaker opens a
dialog that enables you to:
Choose from a number of templates.
Create a blank document by clicking on one of
the Use Blank Paper buttons.
If you click on Custom, FrameMaker displays the
Custom Blank Paper dialog, shown in Figure 1. This
enables you to choose a page size, margins, number
of columns, and single or double-sided pagination.
Your document’s master pages, and the objects
FrameMaker places on them by default, depend on
the choices you make in this dialog. For example,
selecting Double-Sided creates a blank document
with two master pages, Left and Right, which have
mirrored inner and outer margin layouts.
FrameMaker applies default master pages
to every body page automatically unless you
override it. With a document open, selecting
View>Master Pages displays a master page: the
master page displayed will be that applied to
the body page displayed before you switched to
master page view. You should see something like
Figure 2 (which has been truncated). There are a
couple of things to notice about the master page:
The view’s bottom border says ‘Right (2 of
2)’, indicating that you are viewing the Right
master page. (The other, obviously, is the Left
master page.)
FrameMaker has created three text frames on
the page: a header frame, a main text frame,
and a footer frame.
40 Tools
You view and work on FrameMaker master
pages in the same way as you do body pages.
For example, you can draw or place graphical
objects on a master page, and they will then
appear on any body page that uses that master
page. However, there’s an important difference
between master pages and body pages: if you
use the text frame tool to draw a frame on a
master page, FrameMaker will ask you what the
frame is for, displaying the Add New Text Frame
dialog (Figure 3). To understand how this works,
we need to look at the different ways in which
FrameMaker uses master page text frames.
Figure 3. Add New Text Frame dialog
Two types of master page frame
Text frames on master pages are of two types:
background text and tagged flows. FrameMaker
handles these very differently. As Figure 3 shows,
tagged flows are identified by alphabetical flow
tags. A helpful way of thinking about flows is
to think of them as stories: if, for example, you
are laying out a newsletter, you might wish to
continue a front-page story on an inner page.
A separate flow enables you to do this. For
documents such as reports, books, manuals,
and so on, you would normally use only one
flow. You can tell tagged and untagged flows
apart by selecting them and then selecting
Graphics>Object Properties to display the
Customize Text Frame dialog — a tagged flow
will have a flow tag, while a text frame used for
background text will not. (To select a background
frame, you must be displaying master pages.)
The Customize Text Frame dialog is also
where the text flow can be set to display
multiple columns — don’t be tempted to create
separate text frames on the master pages for
this. FrameMaker can also be asked to balance
columns to equalise the amount of white space
on partial pages.
In Figure 2, the header and footer frames are
untagged, while the main text frame has the
flow tag A by default (although you can give a
flow any name you want). When you are working
on body pages, FrameMaker displays the flow
tag at the bottom-left of the document window.
To create a new master page, select Special>Add
Master Page while displaying master pages. The
Add Master Page dialog offers you the option of
creating an empty master page (one with no text
frames), or a copy of an existing master page. You
can then edit the new master page as required.
How FrameMaker uses master pages
The simplest case is a single-sided document
with one master page, which FrameMaker calls
(perhaps a little confusingly) Right by default.
The main text frame will have a flow tag A and
the Autoconnect property — about which more
below — will be on.
As you add text to the first body page,
FrameMaker places it in the main text flow
(frame) until the end of the frame is reached.
When you add more text or graphics, referred to
as ‘overmatter’, FrameMaker creates a new page
and frame to accommodate them.
This ‘word processor-ish’ behaviour is what
is normally required in books, manuals, reports
and so on, and seems natural. However, if you
are working using custom page layouts, for
example in a magazine layout in which each
page is different, overmatter is a potential
problem. You don’t want a new page to be
created automatically: overmatter might be
relegated to a distant page later in the magazine
or newsletter, or might need to be cut entirely.
You can prevent FrameMaker adding
new pages to accommodate overmatter by
disabling the Autoconnect property for the
main text flow(s) on the master page(s), then
reapplying the master pages. FrameMaker
will then indicate the presence of overmatter
by displaying the bottom border of the main
text flow as a solid line, and will not create
new pages for it. FrameMaker provides several
commands for manually linking text flows under
Format>Customize Layout.
In a more complex situation, for example in
which master pages contain multiple text flows,
some of which have Autoconnect on and some
of which do not, the Autoconnect flag is always
honoured — pages and frames will not be created
to accommodate overmatter if Autoconnect is
off for the flow, even if additional pages already
exist that contain frames belonging to that flow.
Adding objects to headers and footers
Although you can create as many master pages
as you like, this does not mean that you have to
have a different master page for each different
header and footer. FrameMaker’s running
header/footer variables enable you to add
header or footer text that is based on objects on
the body pages. For example, if you are writing
a user guide in which each chapter is divided
into sections that are titled using a paragraph
tag A-head, defining the Running H/F 1 variable
41
as <$paratext[A-head]> and placing it in the
header of the Right master page will cause the
current major section heading to appear on all
subsequent right-hand body pages.
Page numbers are catered for by FrameMaker’s
predefined variable <$curpagenum>, while
other variables cover things like the page count,
the current date, the date the document was
created, and the date it was last modified.
Applying master pages automatically
Let’s assume that by this stage you have a
double-sided document with three master pages:
the default Left page, the default Right page,
and a special one called First, to be used on
the first page, for example in each chapter of a
book. This is probably one of the commonest
uses for custom master pages.
In a double-sided document FrameMaker
alternately applies the Left and Right master
pages by default: if your document starts on a
right-hand page, FrameMaker applies the Right
master page to it automatically. How then can
you apply the First master page?
You could, of course, display the first page
and apply the First master page to it manually,
using Format>Master Page Layout>Master Page
Usage. However, it is possible to automate this
process, because from Version 7.0, FrameMaker
enables you to associate a master page with
the presence of a paragraph tag (or element, in
structured FrameMaker) on a body page.
This is done using a special flow on the refer
ence pages, Master Page Maps, which contains
a mapping table: UnstructMasterPageMaps
for unstructured FrameMaker documents, and
StructMasterPageMaps for structured documents.
These tables do not exist until you select the
Format>Page Layout>Apply Master Pages
command for the first time in a document.
The master page mapping table for
unstructured documents contains four columns:
The paragraph tag name
The right-hand master page to use
The left-hand master page to use
A range indicator, described below
A comments field, where you can describe
the purpose of the automatic master page
application (very useful later!).
The range indicator has three possible values:
Single (or blank) applies the named left- or
right-hand master page only to the body page
that contains the named paragraph tag.
Span pages applies the left and right-hand
master pages to the body page range from
the first to the last occurrence of the named
paragraph tag.
Until changed applies the named left and
right-hand master pages until either a further
master page mapping is triggered, or the end
of the document is reached.
So, in the example of our First master page for
a book chapter, we could create a paragraph tag
ChapHeading to format the chapter heading,
and an entry in the UnstructMasterPageMaps
table as follows:
Paragraph tag name: ChapHeading
Right-hand master page: First
Left-hand master page: (blank)
Range indicator: Single.
When you then select Format>Page Layout>
Apply Master Pages, FrameMaker will apply the
First master page to any right-hand body page
that contains a paragraph of type ChapHeading,
and only to those pages.
Adding static page objects
Master pages are also used for adding page
decorations, such as graphics that appear in the
same place on each page on which they are used,
or coloured page backgrounds.
With a master page displayed, you can select
File>Import>File to import a graphic directly
onto a master page. FrameMaker places the
graphic centrally on the page. This not always
terribly helpful, as it is likely to land behind the
main flow frame, making the graphic unselectable
unless you apply Graphics>Send to Back to
the main flow frame. The simplest way around
this is to draw a graphic frame on the master
page using the graphics frame tool on the Tools
palette, then import the graphic into that.
One thing that’s worth remembering, which
can cause some confusion, is that objects placed
in tagged flows on master pages do not appear
on body pages: to display a background object
on a body page, you need to place it in an
untagged flow or graphic frame.
Dynamic objects on master pages
By now you could be forgiven for thinking that
master pages are a little dry and dusty:
necessary, but not particularly exciting.
However, with a little cunning, it’s possible to
place dynamic objects on master pages. By
‘dynamic’, I mean objects on a master page that
can be made to move and/or display differently
on body pages, under the control of features
such as autonumber threads, paragraph formats,
markers and so on. We will look at how this can
be done in the next article in this series. C
For more information
Most of the FrameMaker features described
in this article are covered in the FrameMaker
User Guide and on-line help. You can find full
details of master page mapping in the user
guide. The FrameUsers site and mail list are also
recommended resources: www.frameusers.com.
Steve Rickaby BSc MISTC
has been a freelance
technical author and
editor for 16 years, and
has used FrameMaker for
most of that time.
E: srickaby
@wordmongers.com
W: www.wordmongers.com
42 Affiliate news
IBM accessibility technology
caters for varied disabilities
As part of the new IBM Global Services
consulting specialty in accessibility,
IBM’s WebAdapt2Me software has been
installed at California State University
to help its students and faculty gain
easier access to the Internet. IBM
consultants are helping the university
to improve access to websites and
web-based applications for members
of the university community who have
disabilities, as well as those who need
help accessing the Internet because of
age-related vision or motor difficulties.
The software benefits a diverse
spectrum of people, enabling them to
view websites in the most productive
way for them. For example, people with
low vision can change the size of the
type, and the colours and contrast of
the page, for easier viewing. People with
learning disabilities can reduce visual
clutter on the page (for example, by
reducing several columns to one) so they
can follow the text more easily. People
without full mobility can set up their
system so the mouse and keyboard are
easier to use. And people with learning
disabilities can ask WebAdapt2Me to
read the text on the screen aloud, using
IBM ViaVoice technology.
IBM consultants are working with
campus IT staff to provide accessible
information to students and staff with
disabilities at Cape Breton University
in Canada, Tokyo Metropolitan and
Nagano Universities in Japan, and
Bologna University in Italy. IBM is also
running a pilot programme at Wake
Forest University in the US, where
students are testing speech-enabled
web-based applications on hand-held
devices like phones and iPods.
‘With IBM’s long-standing interest
in advancing higher education,’ said
Frances West, Director of the IBM
Human Ability and Accessibility
Center, ‘It is a natural fit for us to work
with institutions of higher learning
to transform the way education is
delivered to all students.’
Cherryleaf to launch MadCap Flare courses
technical information. Originally
developed by IBM in 1999, the
architecture was approved as a
standard by the Organization for
the Advancement of Structured
Information Standards (OASIS) in early
2005. Current members of the working
group include IBM, Intel, Innodata
Isogen and Sun Microsystems.
In support of the mission of the working
group, Lionbridge has also released a white
paper entitled DITA in Localization: Five
steps to ensure successful localization using
the DITA framework. The paper outlines
best practices for organisations to follow
when implementing DITA, and five steps
to take during the DITA roll-out process
that will optimise the customisation
for future content translation efforts.
Organisations that publish content in
multiple languages will benefit from
the practical information contained in
the paper, designed to assist with their
DITA implementation.
The paper is available at www.
lionbridge.com/kc/DITA.
Now that MadCap Software’s Flare
Help authoring tool has been released
(see pages 22–24), Cherryleaf will be
offering training and consulting to
RoboHelp users planning to migrate to
Flare and to new Flare users. Created
by the developers of RoboHelp, Flare
is a new help authoring tool that will
appeal to users of RoboHelp.
To download a 30-day free trial of
Flare, visit www.madcapsoftware.com.
For more information about
Cherryleaf’s MadCap Flare course, visit
www.cherryleaf.com/flare.htm.
Lionbridge joins DITA technical committee
Provider of globalisation and off-shoring
services, Lionbridge Technologies, has
joined the Darwin Information Typing
Architecture (DITA) working group as a
member of the technical committee. As
a committee member, Lionbridge will
work closely with the group to ensure
that the emerging standard provides
an appropriate methodology for
companies that publish content globally
to translate materials easily from source
language to target languages.
DITA is an XML-based architecture
for authoring, producing and delivering
Gazelle Training publishes detailed case study
Gazelle Training has recently published
a detailed case study regarding its
work developing courseware for risk
The Fourth Annual
Conference on
Technical
Communication
Management
LavaC n
Oct. 1--4, 2006
Kauai, Hawaii
www.lavacon.org
management organisation Lloyd’s Regi
ster. The company has been developing
courseware for Lloyd’s Register since
1995 but has concentrated on Marine
technical software products since 2002.
At the beginning of 2003, Lloyd’s
Register’s Ship Design Systems (SDS)
department expanded the development
of its software products. This highlighted
the need to streamline the courseware
development process without
compromising quality. In May 2003,
Lloyd’s Register commissioned Gazelle
Training to identify and implement a
comprehensive object-oriented database
with content management. The priority
was to find a system that would
facilitate the reuse of text and graphics
in several different outputs. The design,
development and implementation of the
project using AuthorIT was completed
in June 2005. Since May 2005, all
courseware for new projects has been
developed using AuthorIT.
Currently, Gazelle Training is
implementing AuthorIT in another
department at Lloyd’s Register and
the company continues to work on the
development of courseware for Lloyd’s
Register. To read the detailed report,
visit www.gazelletraining.co.uk.
43
Industry news
www.appliedlanguage.com wins web award
The website of translation agency
Applied Language Solutions, www.
appliedlanguage.com, has been
honoured in the 10th Annual Webby
Awards. It was awarded Official
Honouree status by the board of judges
which includes David Bowie, Internet
inventor Vinton Cerf, Naked Chef Jamie
Oliver, The Body Shop president Anita
Roddick, fashion designer Max Azria,
Simpsons creator Matt Groening and
Real Networks CEO Rob Glaser.
The 10th Annual Webby Awards
received over 5500 entries from more
than 40 countries worldwide. The
Honouree award is only given to the
top 20% of all the entrants.
Richard Michie, Marketing Manager
for Applied Language said ‘This is a
great achievement for all the team who
helped to put the site together. It’s
especially satisfying when you take a
look at all the other websites which have
been honoured; there are some really
big names who have far bigger teams
and resources than we have. This award
is a testament to all the team who’ve
worked so hard on the site, especially
the Bulgarian team of programmers
and designers: Lilia, Hristo, Stanislav
and Tsvetomir. Without them, this could
never have been achieved.’
The board of judges select sites
for recognition based on excellence
in content, structure and navigation,
visual design, functionality, inter
activity and overall experience.
Research to investigate how technology
affects social relationships
A research grant of £0.5 million
has been awarded to three northern
universities to pursue ground-breaking
research into how new technology
affects the size and make up of social
relationships. The Universities of
Manchester, Liverpool and Sheffield
Hallam will use the cash to invest in
an emerging field of science, known as
computer-mediated communication.
Lead by Professor Alistair Sutcliffe
from the School of Informatics at The
University of Manchester, the research
will investigate how mobile phones and
the Internet affect the size and make-up
of contemporary social relationships.
Funded by the Foresight Programme,
the project is based on the theories of
evolutionary psychologist Robin Dunbar
from the University of Liverpool, which
state that human beings naturally congre
gate into groups of about 150. He said,
‘Innovations such as mobile phones,
newsgroups, iPods and blogs are helping
to establish worldwide communities.
However, it is not clear how — or even
whether — these technologies are changing
the size and nature of our natural
social groupings. In an era of IT-driven
communication, we will need to understand
better how technology facilitates social
processes in group-based tasks. Do they
help, or do they hinder? Our aim is to
create theories which will shape public
policy, use the Internet more effectively
and influence the way the next generation
of computer technologies are designed.’
Conversis named elite startup
Conversis, provider of globalisation,
internationalisation, localisation and
translation (GILT) services, has been
recognised by Real Business magazine
as one of the UK’s ‘50 to watch’ startup
companies. The British business
publication sought to find the most
exciting, innovative and promising new
firms in the UK and selected Conversis
from more than 300 nominations.
The magazine was specifically looking
for ‘interesting people with bold
ambitions, tackling established markets
or creating entirely new ones.’
Conversis has clients that represent
more than a dozen industries in more
than 30 markets globally, delivering
translation and localisation projects
across a wide range of market interests,
including financial services, medical
and pharmaceutical companies and
telecoms providers. To find out more,
visit www.conversisglobal.com.
Nedstat introduces Sitestat In Spanish
European web analytics company Nedstat
has announced the introduction of its
high-end website analytics product,
Sitestat, in the Spanish language. After
Dutch, English, French and German,
Spanish is the fifth language that is
supported by the product. The addition
of Spanish marks the official launch of
Sitestat in Spain and enables Nedstat
to service its clients there better. For
international clients, it means an extension
of the on-the-fly language switch. Users
can change to any of the five languages
within seconds while they are working. For
more information, visit www.nedstat.com.
Day announces enterprise content
management agreement with CSC
Enterprise content management solutions
provider Day Software has announced
an agreement with global IT services
company Computer Sciences Corporation
(CSC) to jointly market and implement
enterprise content management solutions
to the automotive and industrial sectors
in the UK. The agreement means that the
sales and service professionals at CSC will
work closely with Day, delivering a wide
range of industry-independent content
management solutions, such as corporate
portals, multi-site management, brand
protection, collaboration and community
support, and digital asset management.
Specifically, CSC will provide sales
support, requirements planning and
software customisation services for new
joint projects. In addition, the relationship
expands Day’s professional services
network within the UK for existing clients.
Managing Director of Day Software
UK, Allison Woodward, emphasised the
importance of the relationship. ‘CSC
has years of expertise and experience
in complex IT services across a range of
industries. Looking forward, with Day’s
leadership in the content management
standard JSR 170, CSC provides an
essential support in the provision of inte
grated content management solutions.’
Body for business writers welcomes members
The newly established Federation of
Business Writers (FBW) is welcoming
members. Membership is exclusive
to those who receive a salary or a
commission for producing the written
word. Members will have had their written
work published in a journal, magazine,
text book, technical manual, book of
reference or as a work of fiction. In fact,
anyone who earns a living from writing
will be considered, subject to a sample
of their written work being positively
reviewed by the Membership Panel.
Each new member will receive a member
ship card, a certificate and a copy of the
latest newsletter, The Business Writer.
Members are invited to submit articles,
letters, advertisements and, from time to
time, short stories and other written work.
ESTON Training sponsors the FBW
and members are entitled to 10% off
its distance learning courses. For more
information, contact FBW Secretary Wilma
McKerron at wmckerron@gmail.com.
Written by Kathryn Valdal Fourie.
If you have a story for the news pages
contact us at newsdesk@istc.org.uk
44 Indexing
Choose your words carefully
In his second article, Bill Johncocks considers how the terms you put into an
index — and the ones you leave out — influence its usefulness to the reader.
Last issue, I suggested putting yourself
in the reader’s shoes when compiling
an index. This time, I want to look at the
next obvious question: what to index?
Resisting the temptation to cut corners
Casual acquaintances often ask indexers
whether they actually have to read
the whole of each book. It does sound
time-consuming but, nevertheless, the
traditional method is indeed to read
right through a document, pausing after
each section to ask what significant
information it includes (if any), whether
readers will want to retrieve it and what
terms they might think of if they did.
Today, this foolproof approach has a rival
because, with even parish magazines now
drafted on PCs, your computer can select
the terms for you automatically, can’t it?
Certainly, a computer will find all the
occurrences of a word very efficiently.
If we are indexing a guidebook, it will
instantly find every use of ‘Rome’.
These will include many significant
mentions, but also duplication and
some completely useless references
(such as ‘as we saw in the Rome chapter’
and even ‘available everywhere except
in Rome’). It won’t find synonyms (‘the
Capital’, ‘the Imperial City’ or ‘on the
banks of the Tiber’) and the first result
might look something like this:
Rome, 112, 127, 130–3, 134–48, 150,
152–184, 186, 212, 222, 236–7, 261,
267–8, 283, 291, 303, 311, 327
This is hardly user-friendly (ask
yourself how you’d like to scan 17 page
ranges to find which bus will take you
to the Trevi Fountain) but you often see
such horrors in published indexes.
To use a fishing analogy, Internet
search engines are like using a net — if
not a hand-grenade — while a good index
is like fishing with a fly: precise and
targeted (though it should yield rather
faster and more certain results). Another
entry that needs breaking up would be:
Italy, 130–186
That’s because nobody wants to scan
57 consecutive pages to find what they
want. However, you can go too far the
other way:
Coliseum,
getting there, 183
history, 184
opening times, 183
plan of, 183 …
This is simply a waste of space, giving the
reader no more useful information than:
Coliseum, 183–4
Returning to the entry for Rome, it’s
usually accepted that five page references
are the most you should inflict on your
readers under any one heading while,
turning to that for Italy, I’d suggest any
range of more than four or five pages
deserves breaking up with subentries.
So what a computer produces
unaided isn’t an index at all: in fact
it’s a concordance. These have a long
history; they originally listed word
occurrences in the Bible and the first
person to publish one was — some
might think justifiably — burned at the
stake. But concordances survive to this
day and they even seem to meet the
expectations (though not the needs) of
the Internet generation.
There’s an old story of a doctor who
left to attend a conference and asked
his secretary to index the contents of
his filing cabinet while he was away by
making entries under ‘all the words you
don’t understand’! The result might well
have been useful, but it wouldn’t have
been an index. The novice indexer’s habit
of taking this easy way out is known as
‘word spotting’ and again it’s something
a computer could potentially do.
The essential point is that indexes
don’t just list keywords: they identify
and collocate concepts.
Choosing your terms
Well, that’s a lot on what to avoid. What
should you include? Here are a few ideas:
 Products covered and model variations
 Purpose and specification
 Parts
 Controls and techniques for operation
 Actions users might wish to perform
 Substrates and materials
 Conditions affecting operation
 Troubleshooting by problem.
One sensible convention is not to index
under the main subject. This is to
avoid putting nearly everything in the
same place. If your document is about
xylophones, you don’t really want half
the index to appear under X.
It seems that readers expect us to
index headings, and why not, provided
they’re informative? A section title
like ‘tuning the receiver’ is a good
candidate for an index entry although
‘The next steps’, say, wouldn’t be.
Diagram captions too are a rich source
of potential index terms. Try to be
specific and avoid phrases beginning
with weak words. The stories of car
manuals where ‘how to change a bulb’
is indexed under ‘H’ may be apocryphal
but their lesson is plain enough.
Other conventions govern the form
of the chosen word. Usually, concrete
terms — the names of things that can
be counted — are given in the plural;
nouns and noun-phrases are preferred
to adjectives, and inversion is used
only where it usefully collocates related
concepts (thus ‘eclipses, lunar’ and
‘eclipses, solar’ but not ‘holes, black’).
Some rules are so familiar that we
sometimes forget they are rules, like
inverting personal names. Children soon
learn that, to find books by Roald Dahl
in the Library, they look under ‘D’ not ‘R’,
though again the Internet has different
conventions and company names are not
inverted (so put W H Smith at ‘W’).
Similar, common-sense rules govern
alphabetical order and the forms of
cross-references and page locators…
but let’s leave those for another time.
Don’t worry if your first index is too
long. It’s far better to over-index now
and cut later, even though space is
usually tight. If you give the document
the index it deserves, then cut it down
to fit the space available, the cuts will be
rational and the result more usable. It’s
also best to edit your index after a break
of a few days whenever possible.
This has all been worthy but fairly
basic stuff: for those of you impatient
to progress faster, next time we’ll look
at the popular technique of embedded
indexing. C
Bill Johncocks is a freelance Accredited
Indexer living on the Isle of Skye, who
specialises in embedded indexing of
technical documents.
E: bill.johncocks@btconnect.com
W: www.technicalindexing.com
Society of Indexers: www.indexers.org
See why people are calling Doc-To-Help
the one-click RoboHelp replacement.
®
®
Converting to Doc-To-Help® really is easy.
Simply choose your RoboHelp HTML or Word project and click “convert.” Doc-To-Help
automatically converts the content, formatting, and project settings into a build-ready Word or
HTML source project.
Author your new project in any HTML editor
or Microsoft® Word.
Enjoy the freedom of using any HTML editor or Word to author and configure your Help
systems without having to rely on proprietary editors or code. Integrations with
the most popular editors such as Macromedia® Dreamweaver®, Microsoft
FrontPage®, and Word make it easy to use the most powerful editing environments
available to author your content.
More reasons why authors convert to Doc-To-Help:
Feature Rich Help Authoring
Create virtually any Help system such as HTML Help, NetHelp (browserbased), and WinHelp as well as printed manuals from a single source.
Add all standard Help features and advanced elements such as dynamic text
effects, pop-up links, context sensitive Help for Windows and Web applications,
and much more.
Subscription, Support, and Service
Doc-To-Help includes a one-year subscription service delivering updates and new
versions as they are released, as well as free online support. Telephone support
plans are also available.
Technology Roadmap
We publish and continuously update a roadmap so you will always know our
plans for the next major release and for emerging technologies, such as XML
and Microsoft Windows Vista.
The One-Click RoboHelp ® Replacement
VISIT OUR WEB SITE TO DOWNLOAD YOUR FREE TRIAL
www.doc-to-help.co.uk/oneclick
©1987-2006 ComponentOne Europe Ltd. All rights reserved.
All product and brand names are trademarks and/or registered trademarks of their respective holders.
SALES: 0800 328 5271 • +44(0)1460 234636
46 Editing
What does a proofreader do?
As a prelude to our new editing page,
the SfEP explains the role of the proofreader.
The page proof is the first, and usually
the only, chance for authors to see
their words integrated with other
elements such as illustrations into a
coherent whole. From the relatively
‘fluid’ state of raw copy, where changes
can be made easily, we now have a
situation where the work is relatively
‘fixed’ and production is well advanced.
The proofreader’s role is to check that
the editor, designer and typesetter
have done a good job, and to use their
judgement in marking amendments,
considering their implications so that
costs and delays are minimised. A
professional proofreader will:
Compare proofs with edited copy
or previous proofs or, if requested,
proofread ‘blind’.
Check consistency and accuracy of
text, typography and design.
On hard copy, mark amendments
with standard symbols or, if
requested, mark proofs in electronic
format (PDFs) using special software.
Follow the style guide supplied
by the client or the copyeditor, or
compile one to ensure consistency.
Check that the layout is aesthetically
pleasing and logically arranged.
Liaise with the copyeditor and/or the
author to resolve queries.
If required, collate the author’s changes
with their own, rationalising or querying
conflicting instructions if necessary.
Why do I need a proofreader?
It’s a truism that no one should
proofread their own work — no matter
how many times you check it, you will
invariably miss an obvious error. Your
eyes see what’s on the page but your
brain interprets what it wants or expects
to read, not always what is actually there,
and it takes a ‘fresh eye’ to break this
pattern. Professional proofreaders are
familiar with the production process,
and know what needs to be checked
at each stage, which changes are
uneconomic and how to minimise the
effects of necessary corrections.
Can I do it myself?
As author, you may decide to
proofread your work yourself. The
following guidance assumes that the
book has been edited to an adequate
standard. If extensive changes are
needed at proof stage, you will need to
consider the implications of cost and
timing on the project.
Compare the proofs with the edited
copy line by line.
If you’re proofreading ‘blind’ (that
is, not against copy), use the ruler
method to stop yourself skipping
words unconsciously.
Check that page numbers are
consecutive and running headings
are correct.
On hard copy, identify changes,
preferably with the standard BSI
marks, and mark amendments
accurately and consistently.
Don’t be tempted to re-edit the work
at this stage — acceptable changes are
corrections to typographical errors,
minor adjustments to grammar,
spelling and inconsistencies but not
restructuring or rewriting.
Follow the style guide, if supplied,
or compile your own to ensure
consistency.
Watch out for typographical and
design inconsistencies and well as
textual ones.
Cross-check chapter titles with the
table of contents; check that end matter
corresponds with the text. Check or
insert numbers in cross-references.
Eliminate inelegant or confusing
word breaks, column breaks and
page breaks.
Ensure that illustrations and their
legends and labels correspond with
each other and with the text.
Check that each page is aesthetically
pleasing and logically arranged.
Engaging a professional proofreader
Some of the skills to look for in a
professional proofreader include:
Training in proofreading (such
as courses run by the Society for
Editors and Proofreaders or the
Publishing Training Centre)
Proofreading experience
Specialist knowledge
Communication skills
Knowledge of English
Good judgement and attention
to detail
Knowledge of the production process
Ability to stick to deadlines and
budgets.
You may discuss the work initially
by phone or in person. If so, follow
up by e-mail or letter right away with
what you’ve agreed. When you send
the job to the proofreader, include the
following information:
List — of enclosures and outstanding
material (and date expected);
administrative requirements.
Tasks to be performed — read against
copy/previous proofs or ‘blind’?
Differentiate editorial and
typesetter’s errors?
Important features and relevant back
ground — who is the target audience?
Is the book in a series? Is there a
house style or design specification? Is
the work to be published in electronic
form? Are there any specific requests
(for example, from the author)? Has
anything been decided of which the
proofreader should be aware? With
whom should the proofreader liaise
over queries (give all contact details)?
Illustrations — are labels on line
drawings to be proofread? If any
are copyright, has permission for
reproduction been obtained?
Agreed dates, fee, expenses;
payment period. C
Resources
BS 5261C:2005 Copy preparation and proof
correction. Marks for copy preparation and
proof correction (extracted from BS 52612:2005).
SfEP Code of Practice
www.sfep.org.uk/pages/sfepcop.asp
SfEP Directory of Editorial Services
www.sfep.org.uk/pages/directory.asp
For further details on proofreading, contact
the office of the Society for Editors and
Proofreaders.
T: 020 7736 3278
E: administration@sfep.org.uk
W: www.sfep.org.uk
47
Illustration
Taking a closer look
The ITEDO team presents some examples to demonstrate
what can be achieved by highlighting details in illustrations.
A detail illustration is a means of
highlighting elements in the main
illustration. Its appearance depends on
what the illustrator aims to achieve.
In most cases, detail illustrations are
used to show more information about
portions of the main illustration. As
this often means at a larger scale, the
term ‘magnifier’ is sometimes used.
However, you do not necessarily have
to enlarge a part to add information. For
example, you may want to add emphasis
rather than detail. The mere fact that a
portion of the illustration is shown in
a separate frame may be sufficient to
attract the viewer’s attention.
Most important is how you draw
the highlighted portion. The level of
abstraction in a detail illustration should
support its purpose. A typical use is to
show a small but important item in a
parts illustration (Figure 1). To make the
part as recognisable as possible, you may
omit unnecessary detail and show only
the characteristics needed to identify it.
You may label it with its part number.
When a detail illustration is used to
show a portion of an illustration more
clearly (Figure 2), an enlarged view is
certainly the best choice.
You can also incorporate other stylistic
devices in detail illustrations; for example,
you might choose ghosting or trans
parency to convey more information. You
might even use a different perspective.
Detail illustrations may be enclosed
in any shape, including circles, ovals
and squares, and be connected to the
main illustration by lines or arrows.
Adding a white frame to the inner
contour helps to distinguish the
content from the enclosing shape.
You can highlight several details in
one illustration (Figure 3), provided it
does not become overcrowded. To help
the reader, detail sequences are usually
numbered. Creating each detail on a
separate layer enables you to show and
hide it as needed. C
Bettina Giemsa is responsible for
marketing at ITEDO Software in Germany,
vendor of the technical illustration products
IsoDraw and IsoDraw CADprocess.
E: BettinaGiemsa@itedo.com
W: www.itedo.com
Figure 1. Showing small parts
Illustration: Mosler MT900S road car
created by Harber Technical Services
(www.harbertech.co.uk), Suffolk (UK).
© Breckland Technology
Figure 2. Showing a part in more detail
Illustration: Hammer drill workings created for
Bosch Power Tools GmbH by Altec Graphics Ltd
(www.altecgraphics.co.uk). © Altec Graphics Ltd
8x
Figure 3. Using three numbered magnifiers in one illustration
Illustration: Decoder assembly created for Gebr Märklin & Cie GmbH by VteG GmbH (www.vteg.de).
© VTeG GmbH, with kind permission of Gebr Märklin & Cie GmbH
48 International standards
ETSI guidelines for user setup and education
Richard Hodgkinson reports on the development of European guidelines
for user setup and education of mobile terminals and e‑services.
Background
What is ETSI HF STF 285?
The eEurope 2005 Action Plan aims to
provide a favourable environment for
the creation and uptake of new services
and new jobs, boost productivity,
modernise public services and give
everyone the opportunity to participate
in the global information society.
Already, Information and Communi
cation Technologies (ICT) play a key role
in the daily activities of many people. The
mobile telephone is a highly successful
device. Increasingly, new applications and
services are used to perform necessary
and entertaining tasks. With technical
development offering seamless and
more continuous access to broadband
networks, the vision of a world where ICT
resources around us improve the quality
of our lives is achievable.
Connectivity and interoperability
between telecommunications networks,
personal computing, the Internet and
ever-smarter mobile devices and services
offer enormous potential for improving
the quality of our lives if used by all.
However, there is concern about whether
these new products, services and their
content will be fully accessible to all
people, including children, ageing and
disabled users. An effective e‑society
relies on the fact that all citizens have
access. Users who cannot complete
the initial setup of their devices, the
configuration of services and integrated
or additionally offered applications will
be excluded from the e‑society. Ensuring
access to mobile communication for
all is the common goal of vendors,
operators, service providers and users.
ETSI Human Factors, Specialist Task
Force 285 was formed in March 2005,
and its experts represent standardisation
bodies, manufacturers, service providers
and research. Its objective is to develop
two ETSI Guides (EG):
• ETSI EG 202 416: HF
User interfaces; Setup procedure
design guidelines for mobile
terminals and e‑services
• ETSI EG 202 417: HF
User education guidelines for
mobile terminals and e‑services.
The drafts of both guidelines are well
advanced and publication is planned
for December of this year.
What is ETSI?
The European Telecommunications
Standards Institute (ETSI) is responsible
for the standardisation of ICT, including
telecommunications, broadcasting and
related areas such as intelligent trans
portation and medical electronics. A
non-profit organisation, its members
include manufacturers, service
providers, research bodies and users.
ETSI standards are available free
of charge, although only publicly
available drafts and publications can
be downloaded. For more information,
visit www.etsi.org.
ETSI EG 202 416: User Interfaces: Setup
procedure design guidelines for mobile
terminals and e‑services
The present document provides user
interface design guidelines for the
implementation of setup procedures
with an emphasis on mobile access
to these services. It identifies bestpractice solutions for configuration of
devices and services throughout the
product and service life cycle. Based
on these solutions, the document
provides guidelines that can be used to
develop systems that are usable by and
accessible to all users.
The design guidelines provided by
the present document are focused
towards the design, specification,
development, implementation,
deployment and sustaining of massmarket consumer services and devices;
they are, however, equally applicable to
professional services and end users.
For the purpose of the present
document, access to these services is
achieved through handheld devices
which are typically characterised by a
limited screen size, a 12 key-keypad
and possibly, additional function keys
or, alternatively, a stylus and/or a
touchscreen.
Wherever possible, a design-forall approach has been adopted,
taking the special needs of children,
elderly users and users with physical,
cognitive, or sensory impairments
into account. When appropriate,
specific guidelines for these groups are
presented; otherwise, existing guideline
documents are referenced.
ETSI EG 202 417: User education guidelines
for mobile terminals and e‑services
The present document provides
guidelines for the development,
presentation and evaluation of user
education such as paper-based user
guides or digital help systems for mobile
terminals and e‑services. The aim of the
present document is to provide generic
guidelines, based on broad consensus,
that help increase the uptake and usage
of mobile e‑services for available and
emerging mobile infrastructures.
Appropriate examples of best
practices are provided to ensure that
users will receive instructions and other
guidance that are appropriate to their
level of expertise and abilities, using
media or a combination of media that
benefits the largest range of users; and
that are structured in a way to offer
good navigation throughout the guide.
Wherever possible, a design-for-all
approach has been adopted, taking
the special needs of children, older
users and users with physical or
sensory impairments into account. It
is acknowledged, however, that some
users with very extensive and complex
disabilities may have requirements
beyond the level addressed in the
guide. Furthermore, mechanisms for
user instructions are explored that
facilitate the production of specific
versions of user guides, addressing
users with specific requirements.
Copies of the draft standards will be
available from http://portal.etsi.org/
STFs/HF/STF285.asp C
Richard Hodgkinson FISTC has been
involved in the development of ISO IT
standards since 1990 and represents the
UK on three international committees. He
is a member of ETSI HF STF 286 – Access
symbols for use with video content and ICT.
E: Richard_Hodgkinson@btinternet.com
49
Translation
Taking the pain out of translation
Susan Eustace reveals how translation can help you to stay healthy around the world,
helping medical staff to diagnose your condition and select the best treatment option.
Imagine you collapse after a long-haul
flight and are taken to hospital, where
the medical staff want to put you on
a glucose drip. Would you be able to
tell them you are diabetic? Would a
first-aider know that you were having
a seizure, not an asthma attack, if
you suffer epilepsy? And if you are
on blood-thinning drugs that could
prevent clotting if you haemorrhage,
how would a doctor or nurse know?
There are many advantages to
carrying details about your medical
conditions in the local language when
you travel, and Transmedi has the
solution. It provides a unique service
that can speed up diagnosis and
prevent patients receiving the wrong
treatment due to language barriers.
Your details ready to hand
Covering languages for over 100
countries and taking the form of
a driving licence-style card, the
emergency record lists medical
conditions and allergies in English
and the language or languages of
your choice, reflecting your itinerary.
The record enables those travelling
abroad — especially independent
travellers — to ensure that the staff
who are treating them are aware of
their current medical conditions or any
medical history or allergies that may
affect their treatment.
Medical staff can also access the
information from a secure webpage,
using the two identification numbers
on a Transmedi access card to log on
and retrieve vital medical history in a
language they can understand. Finally,
translated information relating just to
allergies can be sent to your mobile
phone before you travel.
Transmedi evolved as a specialist
arm of my translation business to
address widespread concerns about
travel and health. With many overseas
workers and students coming to
Britain, the Transmedi system has
benefits here in the UK, too, where it
could help ease pressures on British
doctors and local authorities.
A special kind of translator
People often ask me why they shouldn’t
just use free online translation services
rather than paying for translations.
That is like opening the dictionary and
taking the first word — dangerous and
not to be recommended because, in the
end, the human translator will always
need to intervene.
The translators we use for translating
medical and allergy information are
all professionals with experience and
expertise in this area. They will often
have a medical background and always
have a thorough understanding of
drugs and/or in-depth knowledge of
the technology used in the industry
and of how things work.
In terms of tools of their trade,
medical translators, like those
in other fields, make use of
dictionaries — in this case, scientific
and medical dictionaries — but they are
particularly aware of the limitations
of such references. A great deal of
the terminology used in medicine in
certain languages is based on Greek
and Latin words, prefixes and suffixes,
but in English, we tend in some
registers to use Anglo-Saxon terms
(such as gut, bowel movement, lung
infection or lifespan) rather than their
Latin or Greek equivalents (intestine,
defecation, pulmonary infection or
longevity). Moreover, advances in
medical and surgical procedures
require the translator to keep up to
date with new terminology in both the
source and the target language.
Translators also need to be
knowledgeable about the procedures
involved in licensing drugs. While
a drug is undergoing experimental
and clinical tests prior to approval
and launch, it has different names
and labels that are important to the
manufacturer and official regulatory
bodies. The translator has to be aware
of these, particularly because, prior
to licensing, drugs usually have a
chemical and a structural name that
relies on a code to keep the drug safe
from the attentions of competitors.
Then, once tested and approved,
drugs will also have a generic or nonproprietary name, such as nifedipine,
which is recommended for all medical
communications.
If the manufacturer is successful
in patenting the drug, it may then
use a proprietary name or registered
trade name, such as Procardia® or
Adalat® in the case of nifedipine.
However, pharmacists worldwide hold
international drug reference books or
have access to online publications, and
can use this unbiased information to
find the content and compounds of any
drugs and related substances in clinical
use. This means that translation is not
required for actual drug names.
Read the label
Drug manufacturers are also required
to use only approved labelling, which
sets the tone for the claims that may
be made in the literature and package
inserts or on labels before a drug is
approved for marketing. Translation
for labels and inserts could involve up
to three translators: one to translate,
another to edit and a third to check
quality. This, of course, means three
sets of translation costs.
So-called back-to-back translations
are also used, a process in which one
translator translates into the target
language, a second translates back
into the source language and a third
edits and checks quality. The process
is labour-intensive but guarantees the
quality and accuracy required.
After all, where medical and
pharmaceutical translation is involved,
lives are at stake. C
Susan Eustace is Managing Director of The
TransLation Crew and founder of Transmedi,
an emergency medical service providing
translations of medical details.
E: susan@translationcrew.com
W: www.transmedi.com
Translation page editor: Janet Fraser.
E: J.Fraser@westminster.ac.uk
50 Member profile
into a logical flow and writing about it
in a manner that is clear, concise and
free of jargon is equally satisfying.
I don’t like the fact that engineers,
sometimes, start to speak extremely
slowly and clearly when you ask them
questions, because they think you are
not going to understand the technical
details in their answers!
You worked as a publications
manager in India. What differences
have you observed in the UK industry?
In this issue, we meet
Poornima KirloskarSaini, the second of our
book review managers.
How long have you been in the
business and how did you start?
I came into technical communication
in 1997 quite by chance. With my
postgraduate degree in Archaeology,
I had not envisaged a career in IT.
However, when I got my first job in
1993 as project manager to develop
educational CD-ROMs on historical
subjects, I was drawn into the software
industry. In 1997, when India finally
accepted that CD-ROMS were too
expensive to make and did not always
help pay the rent, my then employer
Western Outdoor Interactive in Bombay,
decided it was time that I started writing
software requirements and manuals.
And that is how it began. I created
technical documentation for inflight
entertainment software, proprietary
Linux software and software created
for conference systems. It was not
long before I started to create training
programmes and materials as well.
What do you like most and least
about being a technical writer?
I like the fact that, at the beginning
of our jobs, we know very little about
the product for which we are writing.
It is a very satisfying feeling when
you understand the intricacies of the
product, knowing that you have done
so because you have asked the right
questions. Organising the information
In India there is more emphasis on
chemistry among team members for
a project to reach completion. The
process flow follows as a result of the
chemistry. I have been in the UK for a
couple of years now and I have noticed
(with my limited experience) that there
is more emphasis on processes to get a
job done. If along the way there is some
chemistry that is welcomed as a bonus.
Also, I have noticed that the UK is
more aware of accessibility issues, both
in writing and in graphic design. India
still has to formulate and incorporate
accessibility guidelines.
What similarities and differences
do you see in writing for a historical
discipline and more conventional
technical writing?
Information architecture is strikingly
similar between historical writing and
technical writing. When you write for
both, you organise the information
into a logical flow and try to find links
among chapters and ideas.
A glaring difference that I have
found is in the style of language used.
Technical communicators tend to use
language that most people understand.
Historians and archaeologists quite often
assume that people know the terms and
references they use in their writing.
You’ve done a great deal of voluntary
writing and website design while
raising a family. How does this differ
from paid work?
The challenges and rewards are quite
different. Physical meetings in the
voluntary world are very few and so
most of the communication between
team members happens remotely. This
can be quite challenging on occasions
when you would rather discuss ideas in
a face-to-face meeting. The rewards are
many — you get to meet a lot of people
from all walks of life and age groups
and you get a feeling of satisfaction that
you are contributing to a good cause.
One of the projects I am working on
is for a charity called Pratham UK. Its
mission is to provide education to the
slum children of urban areas in India.
The goal is to have children in school
by 2010 and have them learning well.
Funds are raised here in the UK, while
the grassroots work is done by volunteer
teams in India. I perform a treasury and
database function for this charity.
Another interesting project is a
booklet and powerpoint presentation
I am designing for a charity called
REACH. Commissioned by the Home
Office, this is an effort to recruit older
people into the world of volunteering.
I find it very interesting because this is
the first time that I will be designing a
booklet for printing in this country. I
am looking forward to interacting with
printers here and would be interested
to know how they compare with
printers in India, where deadlines are
quite loose followed by a major sense
of urgency just before the release date!
What made you take on the role
of book review manager for ISTC
publications?
I took on this role mainly to keep in
touch with the profession. I started with
Linda Robins last year, when my baby
was about four months old. Managing
the reviews provided a welcome
diversion from changing nappies.
What do you need from members to
improve our review coverage?
Linda has already mentioned how
members could support us in our
review coverage. I would like to add
that it is heartening to have members
volunteer to review books, but we
would like to see more of that interest!
Your career has been very varied.
Where do you see your future?
I hope my career will continue in
software documentation. This is what I
enjoy and I am quite hooked on
keeping up with new technology.
However, a few years down the line, I
would like to write a book on the art
and culture of India. This has always
been a passion with me and I would
like to share it with everyone! C
If you have suggestions for books to review,
or you would like to volunteer your services
as a reviewer, contact Poornima and Linda
on review.manager@istc.org.uk
TRANSLATION
LOCALISATION
AUTHORING
ILLUSTRATION
PUBLISHING
9OUVEGOTTODRAWTHELINESOMEWHEREx
4HEREAREVERYGOODREASONSFORASKING)MPRIMATURTODOYOUR
TECHNICALILLUSTRATIONS
7EHAVEATEAMOFILLUSTRATORSWHOAREEXPERTSATPRODUCINGTHE
HIGHESTQUALITYWORKUSINGAWIDEVARIETYOFILLUSTRATIONTOOLS
!LLOFTHEMAREFULLYTRAINEDINWORKINGWITHTECHNICALAUTHORSTO
ENSURETHEGRAPHICSSUPPORTTHETEXTSEAMLESSLY
!NDWHILSTTHEYAREALLARTISTSTHEREISNOHINTOFARTISTIC
TEMPERAMENTnTHEYUNDERSTANDDEADLINESTHENEEDFORQUICK
TURNAROUNDANDPRODUCTIVITY
3OIFYOUAREGOINGTODRAWTHELINESOMEWHEREnWHYNOTMAKE
THATPLACE)MPRIMATUR
)MPRIMATUR,IMITED
#HERTSEY3TREET'UILDFORD
3URREY'5(,%NGLAND
4EL
&AX
%MAILINFO IMPRIMATURCOUK
WWWIMPRIMATURCOUK

David Pogue`s missing manuals

Transcription

Similar documents

This Manual is provided FREE OF CHARGE from CBTricks.com

TFM-42 service manual

Minding your language Setting procedures in stone

Cut away, explode or animate?

Communicator Summer 2010.indd

AEREON Flare Tip Retrofit Services Marketing Sheet

Power Pick Global Communicator Pro

This Manual is provided FREE OF CHARGE from CBTricks.com