Cut away, explode or animate?

Transcription

Communicator
The Institute of Scientific and Technical Communicators
Autumn 2007
Optimising legacy
document conversions
Unbundling MadPak:
has Flare come of age?
Choosing the right tool:
InDesign or FrameMaker?
Making knowledge
more useful to your users
Cut away, explode or animate?
Finding time to do it all with CAD-based illustration
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: [email protected]
• 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
12
Communicator The quarterly journal of the ISTC
ISSN 0953-3699
Production team
Editor
News editor
Kathryn Valdal Fourie, [email protected]
Copyeditors
Improving the effectiveness of websites
15
18
InDesign CS3 versus FrameMaker 7.x
Philip Odell
Faster, cheaper, better documentation
Karl Darr
Implementing a technical editing system
22
Tony Eyre and Nick Robson
Review of the MadPak authoring suite
Matthew Ellison
Exploring MadCap Software’s latest suite of products
Proofreaders
Tim Joynson and Linda Robins
Layout
Newell-Porter Limited, www.newellporter.co.uk
Advertising
Felicity Davie, [email protected]
or 01344 466600
Subscriptions
Carol Hewitt, [email protected] or 01733 390141
26
Using 3D data in technical illustrations
Matthew Jennings
Summarising the uses of CAD files in illustrating manuals
30
90 years of aircraft history
Gene Sexton
Explaining what makes Boscombe Down a special place to work
34
A framework for organisational structure
Warren Singer
Describing the Zachman Enterprise Architecture Framework
Submissions
Guidelines
www.istc.org.uk/Publications/communicator.htm
Spring
Summer
Autumn
Winter
Kees van Mansom
Taking a look at long document features in the latest version of InDesign
Marian Newell, [email protected]
or 01344 626895
Deadlines
How information becomes knowledge
38
Successful migration of large data sets
Graham Every
Discussing the processes involved in high-volume data conversion
copy by
published
copy by
published
copy by
published
copy by
published
31 January
21 March
30 April
21 June
31 July
21 September
31 October
21 December
Back issues
www.istc.org.uk/Members_Area/communicator_
archive.htm (ISTC members only)
40
Documentation with a wiki: reception
Katja McLaughlin
Evaluating the reaction to delivering guidelines using this medium
42
Touching DITA: linking to other content
Ian Larner
Controlling links to other DITA topics and to external resources
46
First steps in structure: rules
Steve Rickaby
Giving more detail about the rules in element definition documents
50
Industry and affiliate news
52
Editing
53
Book review
54
International standards
The Institute of Scientific and Technical
Communicators (ISTC)
55
Indexing
Carol Hewitt, ISTC Administrator
PO Box 522, Peterborough, PE2 5WX
E: [email protected]
T: +44 (0) 1733 390141
W: www.istc.org.uk
F: +44 (0) 1733 390126
56
Translation
58
Member profile
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.
Printed on recycled paper using vegetable inks and
low volatile organic compound (VOC) chemistry.
Kathryn Valdal Fourie
Jean Rollinson
Paul Newbold
Richard Hodgkinson
Bill Johncocks
Romina Franceshina
Tony Eyre
cover A transfer gearbox by Matthew Jennings of Industrial Artworks,
an example of the use of CAD data in illustration (pages 26–29).
Communicator Autumn 2007
ISTC news
Writing better English
Editorial
In this issue
Welcome to a special issue of
Communicator, containing eight extra
pages and going to many new readers
through the autumn conference circuit.
We have a selection of articles on tools
and methods. For tools, there’s Matthew
Ellison’s review of MadPak, Philip Odell’s
comparison of InDesign and FrameMaker,
and Karl Darr’s description of a bespoke
editing system. For methods, there’s CADbased illustration from Matthew Jennings,
the Zachman framework from Warren
Singer and data conversion from Graham
Every. In addition, Katja McLaughlin (née
Mannerkorpi) revisits her wiki project
(Communicator, Spring 2007) and Kees
van Mansom foreshadows his conference
talk on making knowledge usable.
While pondering the relative merits of
different links between clauses and
sentences in my own writing, I realised
that I would welcome a feature article
on stylistic subtleties in English. I don’t
mean rules for right and wrong but
rather a detailed discussion of phrasing
and its effects on interpretation.
How does one decide where to break
clauses, sentences and even paragraphs
in a piece of text? How does one
decide between different but similar
conjunctions and discourse markers?
If any of you feel able to demonstrate
and explain more advanced writing
techniques, do get in touch. I know
from feedback forms that readers want
to see more articles on writing.
Article writing: tip #6
Plan the content of each section of your
article to suit its importance and the
overall length of the piece. More than
once lately, our production cycle has
highlighted a lack of balance in a
submission. It’s as if writers start off
well but then lose their impetus and
hurry later sections, often just as they
reach the most interesting part of their
topic for our readers. An article I read
recently showed how writers can divide
a 1200-word article into six paragraphs
of roughly 200 words. Your topic may
not suit such an even-handed approach
but do make your allocation of space
deliberate rather than accidental. C
Marian Newell FISTC
Letters
Technical writing: is it artistic creation?
Dr Mike Unwalla FISTC
Standard Industrial Classification (SIC) codes
classify businesses by the type of economic
activity in which they are engaged. From
January 2008, new SIC codes will be
used in the UK. I was dismayed to learn
that technical writing is categorised
as ‘artistic creation’ (and technical
communication is not even mentioned).
A representative from the Office for
National Statistics explained the history and
rationale for the categorisation (available
on www.techscribe.co.uk/ta/sic-codestech-writers.htm). Nevertheless, I think that
technical writing should not be grouped
with ‘activities of individual artists
such as sculptors, painters, cartoonists,
engravers, etchers etc.’ and ‘activities
of individual writers, for all subjects
including fictional writing’. Instead, we
should be categorised under ‘information
and communication’ or ‘professional,
scientific and technical activities’.
What do technical communicators,
particularly those who are technical
writers, think? Would our image in the
marketplace be improved if we were
categorised differently? Should the ISTC
define a position, and attempt to influence
future categorisation of technical
writing and technical communication?
From the Editor: I would like to hear
readers’ opinions on the Standard
Industrial and Occupational Classifications
(SIC 2007 and SOC 2000). The ISTC is
considering a proposal for changes.
everything we print is green...
If you are concerned about ensuring your
promotional materials are both costeffective and environmentally friendly, you
should be talking to us.
As an award winning leader in the
field of eco-friendly printing we
cut out the waste and the costs
to give you a great looking
product within your budget
with a sustainable approach.
tel: 01256 880770
web: www.greenhousegraphics.co.uk
greenhouse | graphics |
Masters courses in Technical Communication
University of Portsmouth
Ian Kemble
Our MA in Technical Communication
is just about to complete its first year
of operation. The course has attracted
students from a range of backgrounds,
including a technical author with the MoD,
a graphic designer wishing to extend
her repertoire into technical writing, an
engineer with British Airways, a primary
school teacher seeking a career change and
a small number of graduate students.
The course is highly collaborative, taught
not only by members of the School of
Languages and Area Studies but also by
colleagues from the Faculty of Technology,
the Faculty of Creative and Cultural
Industries, and the Portsmouth Business
School. Contributions to course modules
are also made by professional technical
communicators, including Matthew Ellison,
a regular contributor to Communicator.
Yes, I know that’s a lock: how do I unlock it?
Bill Johncocks
The two fascinating articles on illustration
in your Summer 2007 issue seemed a
little too enthusiastic to this consumer.
The move to all-pictorial instructions
isn’t driven by customer demand, of
course, any more than are the dreadful
customer services interactions foisted
on us today. It’s intended to cut
translation costs and to allow products
to be easily switched between markets.
IKEA was a leader here, and the two
pieces of their furniture I’ve assembled
are still intact and functioning, but some
manufacturers seem to think any picture is
The course benefits from flexibility, in
that part-time students in employment
need only attend the University on one
afternoon a week, and from its links with
the University’s Partnership Programme,
which offers work-based learning modules.
Students can obtain practical experience
of technical communication through
placements with local companies. This
year’s placements included IBM, VT
Shipbuilding and Lockheed Martin UK.
Recruitment for the session starting October
2007 is under way and continues to the end
of September. Further information can be
obtained from www.port.ac.uk/MATechComm
or from me at [email protected].
Sheffield Hallam University
Dr Mike Beaken
Our MA in Technical Communication is the UK’s
only distance-learning Masters degree in the
subject. Run successfully since 1991, the course
was revalidated this year to bring it up-to-date.
The course is for practising and aspiring
worth a thousand words. Not so! I suspect
fully half the population would prefer
the words and more than half would like
both. Just linking a ‘before’ and ‘after’
state with an arrow, for example, tells
you the intended sequence but nothing
about how to effect the transition.
I recently bought a utility knife; the
kind you must disassemble to insert
the blade. The pictorial instructions for
operating the blade lock consisted of a
padlock image and an arrow pointing to
the lock. This told me it was a lock, which
I already knew, not how to use it. My wife
is a graduate engineer but it took twenty
minutes of her expertise and my colourful
technical communicators, running part-time over
three years and culminating in a dissertation that
applies current theory to professional practice.
It balances an academic, research-led approach
with a review of technical communication
practices. Students consider every step of
the design cycle for printed documents (such
as reports, procedures and instructions)
and online documents (such as online help,
multimedia applications and websites).
All industries and organisations need
skilled technical communicators. This course
is ideal to develop professional communi
cation skills using published distance
learning materials, reflective practice and
interactive participation online. Students
must have easy access to the Internet.
Find out more at www.shu.ac.uk/media/
postgraduate/index.html, http://extra.shu.
ac.uk/acespg/pgcoursehandbooks and www.
shu.ac.uk/study/form.html. The next course
starts 24 September 2007, with another intake
in January. If you have any questions, contact
[email protected] or +44 (0) 114 225 5280.
language to work it out. A dozen words
would have saved all that time so in
future I’ll buy another type of knife.
Pictorial instructions are no panacea.
They will create a few jobs for illustrators
but destroy those of many writers and
translators. As IKEA recognises, they
need usability testing as thorough as
that for text-based instructions, and in
every likely market, to ensure they are
comprehensible and unambiguous.
We welcome letters of up to 200 words but
reserve the right to edit as required. Write
to [email protected] or PO Box 522,
Peterborough, PE2 5WX.
www.bedfordtrans.co.uk
We’re talking
your language
Our experienced teams work with technical authors in major
companies worldwide, providing a reliable professional language
service in all disciplines.
19-19a ST ANDREWS ROAD · BEDFORD MK40 2LL · UNITED KINGDOM
TEL: 01234 271555 FAX: 01234 271556
Translation: manuals, patents, documentation
Publishing: your preferred application
Localisation: software & marketing information
Globalisation: your web presence
We comply with the new Translation Products Standard BS EN 15038.
ISTC news
Outgoing presidential address
Communicator
Oxford Reference Online
Thanks to a wonderful team, this has
doubled in size, with production more
than half-funded by advertising. Content
and advertising is now booked well in
advance and Communicator is recognised
internationally as a top publication.
We all have access to 30 OUP
publications through our website.
Newsletter
Business Affiliates
Thanks to its editors and our
advertising agent, our newsletter is
now regular, reliable, informative and
fully funded by its own advertising.
The ISTC now has 26 Business Affiliates,
including some of the biggest and most
successful companies in our profession.
They enjoy many discounts and privileges
and bring more skills and talent to our
online groups and membership in general.
Website
This is my final address before handing
over the reins of the ISTC. It’s hard to believe
that it’s been five years. There have been
difficult situations, tough decisions and hard
work, but I’ve enjoyed it all. It’s been my
pleasure to run the Institute on your behalf
and I hope I’ve done the position justice.
A little while ago, I said that I’d already
achieved my aims for my Presidency and
that I needed to think of more. Well, I did
and I think now would be a good time to
reflect on the changes to the ISTC during
my term and how they may continue.
Conference
We’ve gone from a small members’
gathering to a sponsored, international,
self-funding, professional Conference.
Last year’s change from weekend to
midweek only advanced the event further.
At the time of writing, Conference 2007
promises to be the most successful yet.
The ISTC website has been redesigned
and re-organised and the result is easy
to use, easy to navigate and a good
advertisement for our Institute.
ISTC Training
The ISTC is now a training provider with
three tutors, more than 40 students and
plenty of interest to take it further. We are
also the owners of the official syllabus,
which other training providers will use,
and next year we will launch examinations
to fill the gap left by City & Guilds.
British Standards
ISTC members have a 15% discount on
British Standards ordered through the ISTC.
Professional Associations Research Network
Our membership of PARN has already
proved to be very useful. With links to
others in the professional association
sector and our participation in research
and enquiries, it has been an invaluable
aid in keeping the ISTC on the right path.
Online groups
All these have two things in common:
1. They couldn’t have been done without
the hard work and commitment of
my fellow Council members.
2. They were done to improve the ISTC and
make things better for us, its members.
I’ve not stopped believing in the ISTC
since I joined and I don’t intend to stop
now, so I’ll be around for some time yet.
Once again, thanks to all of you for your
support and help over the years. C
This one is purely thanks to you all.
The groups are flourishing with lots of
members and active, useful discussions.
Gavin Ireland FISTC
ISTC Books
Our first book is in production and
signals the start of the ISTC publishing
relevant and useful books.
2007 ISTC Conference
2-4 October 2007
For full details, visit:
www.istc.org.uk/Events/Conference/
conference_2007.htm
The technical communication culture
Only £355 + VAT
Britannia Adelphi Hotel
Ranelagh Place
Liverpool
L3 5UL
For bookings or
more information,
telephone Ann Little on:
020 8422 4689
or e-mail her at:
[email protected]
Mike Austin award presented to John Young
Council has awarded the 2007 Mike Austin
award for outstanding service to the ISTC
to John Young. The award is presented to
someone who has made a considerable
contribution to the ISTC over a period of
time. With 27 years’ service on Council,
John has certainly done this.
John began his Council career while
Secretary of the ISTC’s Wessex Area Group,
at which time he was already a lecturer
on the Technical Authorship course at
Chippenham College. Geoff Brand, a
colleague there, says: ‘I am glad to see John
being honoured — it is certainly deserved.
John worked at the college for many years
and made it a centre of excellence for the
training of technical authors. He was a
popular and effective teacher, establishing
strong links with industry to the extent
that Chippenham graduates were always
in demand. His approach was informed,
patient and open-minded — demonstrated
by his work with a wide range of students
from many backgrounds. He was also a
popular and respected member of staff
and is greatly missed.’
ISTC President, Gavin Ireland, recalls: ‘I
went on a resettlement course taught by
John. He was a great teacher, supportive
throughout the course, and an ISTC
enthusiast. Little did I know then that
I’d be working with him on Council now,
where he has been just as helpful. When
the opportunity arose for the ISTC to
run a training course, develop a syllabus
and launch examinations, John led the
way. He will be missed on Council and I
wish him the best for the future.’
The ISTC’s incoming webmaster, John
Lee, was another student. He says ‘John
was always there, ever helpful, and guided
us with the same quiet manner that I have
seen since I joined Council. If he had a
loud or angry side I never saw it.’
In 1991, John took on liaison with
the National Council for Vocational
Qualifications and set up a working
party. This paved the way to the
development of occupational standards
in technical communication (www.istc.
org.uk/Communication_Resources/
National_Occ_Standards/nos_home.htm).
A former ISTC President (1993–5),
Peter Greenfield, recalls that John was
the ISTC’s link to the City and Guilds
of London Institute throughout his
time on Council. John maintained the
relationship through times when C&G
would not continue exams unless they
were self-financing. He played a key role
in keeping the technical communication
qualifications alive. Without people like
John, Philip Hutton-Wilson and John
Crossley, Peter believes we would have
lost them long before we did. John also
maintained technical communication
courses throughout his years at
Chippenham College, one of the few
places that kept training going reliably.
Marian Newell FISTC
Localization into all
main languages
• Expert application of industryleading tools and software
3di has significant experience
in localizing:
• Scalable and robust IT
infrastructure
•
•
•
•
Software products
Online help
E-learning & CBT
Websites
• Ability to localize, recomplie
and test applications on all
major hardware or software
platforms in most languages
ISTC members can purchase British
Standards at 15% discount. Click
Resources on the ISTC website at:
www.istc.org.uk
John resumed leadership of the Education
Steering Group in 2004. He liaised with
the University of Portsmouth during the
establishment of its new postgraduate
qualification. In 2005, following John
Crossley’s sudden death, he arranged for
the ISTC to purchase the course materials
from the estate and offered to set up ISTC
Training. Later that same year, the C&G
announced its decision to withdraw its
qualifications. John took this in his stride,
establishing a working group to develop
replacement qualifications, and his feet
can hardly have touched the ground
since! He has written course materials,
tutored students and recruited new
tutors. Although he retires from Council
at the coming AGM, he remains involved
in course and examination development.
His legacy will be the ISTC’s first provision
of education and qualifications.
Peter Greenfield adds: ‘I worked on a
small bit of the ISTC qualification but, even
then, John’s quiet enthusiasm and good
common sense was in evidence. He has
worked for the ISTC for a very long time
and has always provided reliable support
and good advice on training. I am really
pleased that this has been recognised.’
As well as all his work for the ISTC, John
has written and published a book entitled
Wiltshire Watch and Clockmaker, Volume
1: Chippenham, Swindon, Marlborough
and North Wiltshire. For details, visit www.
wiltshireclocks.co.uk/historymore.htm.
The ISTC’s current President Elect,
Simon Butler, presented the award at
the August Council meeting, where a
formal vote of thanks was recorded for
John’s hard work over the years. We all
wish him well in his retirement. C
• Expert, accessible, & friendly
project management
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
Summer is generally a quiet time for
the Group, and this year has been
no exception. Many of the messages
have been job advertisements for both
contract and permanent positions so,
if you’re an ISTC member looking for a
new challenge, receiving messages from
the Group could be very beneficial!
Software queries
Unusually, FrameMaker rather than
Word has been the source of most of the
software problems discussed on the Group
this quarter. Registration marks, hypertext
links to other documents, and bookmarks
were all issues. PDFs were also the subject
of several discussions; again, hyperlinks
were a popular topic, with group members
asking about hyperlinking index entries
as well as having problems with missing
cross-references.
Active versus passive voice
The familiar authors’ discussion about
the passive voice was raised once
more by a group member whose US
colleagues were worried that all UK
writers used the passive voice too much.
It seems that, in the US, they actively
avoid all use of the passive. The general
Group consensus was that, although
the active voice is preferable for most
technical communication, there is a time
and place when the passive voice can be
correctly used; for example, when the
subject of a sentence is irrelevant.
Capitalisation for compound words
How should compound words be
capitalised in, for example, a heading?
Is ‘Non-functional Requirement’ more
appropriate than ‘Non-Functional
Requirement’? Most replies to this
question favoured capitalising the second
word, to avoid the lack of capitals looking
like a typo, but it was acknowledged
that a lot depends on house style.
Copyright for screens from third-party software
The question of whether permission is
needed to use screen grabs of another
company’s software in your own
publications was raised, for Microsoft
software in particular. A quick
Google by a Group member revealed
that Microsoft is happy for screen
shots of its commercially released
products to be used, provided that
certain guidelines are met regarding
usage, editing and trademarks, and a
copyright statement is included. That’s
probably a relief to those of us who
document Windows-based software!
Trademarks in a topic-based system
A related query was about how and
where to include trademark information
in a topic-based content management
system. Trademarks and copyright are
often listed in a section at the beginning
of a document, which removes the
need to use the appropriate symbols
elsewhere in the text. However, a
member who is migrating to AuthorIT
was concerned that they would
need to use the symbols for every
occurrence. Interpretation of the rules
for trademarks and registration marks
varied, but in general, a note at the
beginning of a document stating that
trademarks belong to their owners was
considered to be enough.
Translations for CE products
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
(Administrator and Company Secretary)
on 01733 390141 or at [email protected] or
PO Box 522, Peterborough, PE2 5WX.
Council members
Photographs at www.istc.org.uk/
About_istc/Governance/istc_council.htm
President
Gavin Ireland
[email protected]
Treasurer
Peter Fountain
[email protected]
There was some anxiety on the Group
about a directive that suggests all
instruction documents for a CE-marked
product must be translated into the
official European Union language for the
country in which the product is used.
With 23 official languages in the EU,
this could be an expensive requirement.
However, individual CE-marking
directives vary as to whether translation
is necessary, and the need for translated
instructions also depends on whether
a country implements the directive
(France and Germany do so strictly).
Checking the EU legislation directly was
recommended as the best thing to do!
Website
To create or not to create?
Iain Wright
[email protected]
Linda Robins
[email protected]
Create, print, convert, export — what’s
the preferred term for the act of
‘making’ a PDF? Because the action
taken varies with the software used,
most group members preferred the
generic term of ‘creating’ a PDF.
However, the specific term should be
used if referring, for example, to
converting a document to PDF. C
Catherine Sharp MISTC
Simon Butler
[email protected]
John Lee
[email protected]
Journal
Marian Newell
[email protected]
Education
John Young
[email protected]
Jim Moore
[email protected]
Marketing
Paul Ballard
[email protected]
Conference
Alan Fisk [email protected]
Other members
Membership committee
Chris Knowles
[email protected]
International representative
Theresa Cameron
[email protected]
Newsletter
Bob Hewitt (layout and artwork)
[email protected]
Kathryn Valdal Fourie (content)
[email protected]
R
10 ISTC news
Independent Authors SIG
http://finance.groups.yahoo.com/group/ISTC_IASIG
Professional indemnity insurance (PII)
Jill Martin asked about professional
indemnity and other insurances. What
level of cover do freelancers have? Which
providers are worth investigating?
PII is often a contractual requirement
in Steve Rickaby’s case. He opts for
the lowest level of cover, usually
£500,000, and increases it if required.
He suggests that most underwriters
do not understand the technical
communication profession, so you may
have to opt for an insurance product
designed for contractors. Quotes vary
greatly; the best price he has found is
on www.contractoruk.com/insurance/
professional_indemnity.html.
While writing this report, I found that
PCG has a Guide to insurance for freelance
businesses on http://tinyurl.com/23uwv4.
Business Link has information about
insurances and an interactive tool to help
you determine what insurance you should
have on http://tinyurl.com/38q67k.
Website development software
Many freelancers have their own
websites. Dave Leonard asked
about getting started with website
development. He wanted a reliable,
easy-to-use, entry-level package.
Two of us suggested that he could
learn HTML and CSS, and use a text
editor. Skills that you learn when coding
manually can be useful when you use a
WYSIWYG tool. Even with these tools, you
will have to edit the HTML occasionally
and add scripts such as JavaScript.
Suggestions from the group were:
EditPad Pro
www.jgsoft.com
NoteTab (text and HTML editor)
www.notetab.com
Programmer’s Notepad
www.pnotepad.org
PSPad
www.pspad.com.
For validation, I use A Real Validator
for HTML (http://arealvalidator.com)
and the W3C CSS Validation Service
for CSS (http://jigsaw.w3.org/cssvalidator/validator.html).
On the other hand, according to Steve
Rickaby, trying to create stylish web
content with a text editor is making
things hard for yourself. He suggested
starting with a shareware WYSIWYG web
editor to keep costs down, and then
moving to industry-standard software
if you decide to do more web work.
Suggestions from the group were:
Dreamweaver — an industry standard
www.adobe.com
First Page 2006 — about £30 at
current exchange rates, with a free
version available (1st Page 2000)
www.evrsoft.com
FrontPage — superseded by
Microsoft Expression Web
www.microsoft.com
Nvu — an open source equivalent
to Dreamweaver
www.nvu.com
A good source of information on free
HTML editors and WYSIWYG tools is
www.thefreecountry.com/webmaster/
htmleditors.shtml.
Richard Pineger suggested using an
open source Content Management System
(CMS), which many Internet Service
Providers (ISP) offer. Typically, the CMS
is a one-click installation, which then
needs to be customised (free templates
are available as a starting point).
CMS tools are often complex, noted
Kim Schrantz-Berquist. For small web
sites, she suggests using free or cheap
website creation tools that ISPs offer
as part of a hosting package. Yahoo
is a good hosting company, and their
templates are the best that she has
seen. Several ISP review sites exist; she
uses www.hosting-review.com.
Dictionaries: online or paper?
Online dictionaries such as the Oxford
Reference online (members can access
this through the ISTC website) and
Google’s ‘define: <term>’ search option
are convenient tools, but Jane Dards
finds printed dictionaries have their
own benefits. With online dictionaries,
she misses all the definitions of words
that she wasn’t looking for, but which
she happens to notice as she turns
pages. This is a good way of improving
one’s vocabulary. From a historical
perspective, old dictionaries can give
new insights. For example, she looked
up ‘computer’ in her old (1966) school
dictionary and was surprised to find
that it was not defined. C
Mike Unwalla FISTC
Member news
New members
Member
Fiona Anthony
Jeremy Browning
Kerry Curran
Robert Dallamore
Elaina Derry
Su Goulding
Simon Green
Noel James
Yousuf Khan
James McGregor
Gordon McLean
Jill Newton
Olusegun Ogunleye
George Reid
Eamonn Smith
James Smithies
Old Ryton Village
Tyne & Wear
London
Bristol
Great Cheverell
Ulverston
Upminster
Preston
Mönchengladbach
Germany
Worthing
Darlington
Hamilton
Basingstoke
Gravesend
Berg TG
Switzerland
Belfast
London
Associate
Katy Gollan
Don Heatrick
Paul Honeysett
Claire Hooper
Cassandra Porter
Dundee
Bury St Edmunds
Swindon
Woking
Leicester
Student
Martin Bekoe
Lynne Duffy
David Hardy
Mike Kennedy
Simon LeMerle
Adrian Searle
Peter Slade
Germany
Tyne & Wear
Harrow
Winchester
Bath
London
Fleet
Transfers
Member
Neil Clifford
Harvey Robson
Ian Wright
Knook
Stevenage
Didcot
Rejoiners
Dominic Andrews Matlock
Philip Davies
Alderney
Channel Islands
Richard Lee
Bristol
Fiona McGregor
London
Stella-Marie Thomas Towcester
Business Affiliates
Bronze
AND Solutions Ltd
www.and-solutions.co.uk
Author Services Technical
www.ast.cc
Innodata-Isogen
www.innodata-isogen.com
Your career. Your future.
Learn the skills you need to go places
Scheduled technical
writing courses
Scheduled application
courses
Other courses available
include
• Introduction to
technical authoring
• Introduction to Adobe
RoboHelp (2 days, £495)
• Autodesk-authorised
AutoCAD training
courses (various)
(1 day, £350)
11 Sept, 13 Nov
• Advanced technical
authoring techniques
(3 days, £795)
15-17 Oct, 3-5 Dec
• Introduction to online
help development
(1 day, £350)
24 Sept, 1 Oct, 5 Nov,
26 Nov
25-26 Sept, 6-7 Nov
• Introduction to Madcap
Flare (2 days, £495)
2-3 Oct, 27-28 Nov
• Basic and Intermediate
Adobe Framemaker
(2 days, £495)
12-13 Sept, 14-15 Nov
• Advanced Adobe
Framemaker (1 day, £350)
14 Sept, 16 Nov
InDesign (2 days)
Acrobat (1 day)
• Using Microsoft Word
to produce user
documentation (1 day)
• Writing with confidence
in plain English (1 or 2 days)
• Writing effective reports
armada
Captivate (1 day, £350)
21 Sept, 23 Nov
(1 or 2 days)
• Writing English for a
global audience (1 or 2 days)
• Writing winning
proposals (1 or 2 days)
For more information or to book, go to
armadaonline.co.uk or call Steven Smith on 01527 834781
www.armadaonline.co.uk
Armada, 6 West Court, Saxon Business Park, Stoke Prior, Bromsgrove, Worcs. B60 4AD
Email: [email protected] tel: 01527 834780 fax: 01527 834785
Scheduled courses take place at our training centre in Bromsgrove in the Midlands, close to the
M5/M6/M40/M42 motorway network. All courses available on-demand at your venue anywhere in the UK.
All prices quoted exclusive of VAT.
armada
12 Methods
How information becomes knowledge
As an introduction to his presentation at this year’s Conference, Kees van
Mansom explains how we can improve the effectiveness of websites.
In our profession, there is a huge emphasis
on creating information: every new product
and every law, policy, rule or process has its
own documentation. And, although content
management systems help us reuse existing
information, the total amount of information is
constantly growing. Finding the right information
within a reasonable amount of time is becoming
more and more challenging for users.
Search instruments and navigation trees do
not offer a proper solution. As users of search
engines like Google and Yahoo know, even the most
sophisticated search engines cannot determine
what information is relevant to the user and offer
long lists of possibilities. On top of this, novice
users often lack the necessary information to
phrase useful inquiries (Horton, 1994). Navigation
trees work fine on small-scale websites but, as soon
as the number of topics grows, both the width and
the depth of the navigation tree grow tremendously.
New semantic technologies enable us to
overcome these problems and offer our users
alternative ways to find and use our information.
Knowledge versus information
Information offers us facts, data or instructions in any
medium or form. The way in which users interpret
this information is based on the context: their
business, the functions within their organisation, and
their working processes, customers and suppliers.
Knowledge is the interpretation of information
Example

Information
The income of students under 18 and living with
their parents has no effect on the child allowance
that their parents receive.

Context
♦You are a student.
♦You are 15.
♦You live with your parents.

Knowledge
Your income has no influence on the child
allowance your parents receive.
within its context. It is the result of perception,
learning and reasoning. Knowledge gives users the
power to make decisions and take effective actions.
Although technical communicators often talk
about providing information to users, they are
in fact creating content that is tailored to their
audience. Technical communicators who focus on
user-centred writing have therefore already crossed
the line from merely providing information to
imparting knowledge (Hughes, 2002).
Developing a knowledge-driven website requires
first of all that we offer the knowledge needed
in a usable and understandable way, in line with
the user’s knowledge and level of experience.
As professional technical communicators, this
is what we do best. The second requirement
is that we should offer our users the right
knowledge — from the enormous amount of
available knowledge — at the right time.
Offering the right knowledge at the right time
Figure 1. Example of a hierarchical navigational structure
As knowledge is the interpretation of
information within its context, we have to
provide a solution that offers us information
based on the context of the user. To do so, we
have to create models of the context. We can use
this context information to provide our users
with smart and flexible solutions, such as:
Non-hierarchical navigation presents a mind
map of the information, with different types
of links making it possible to browse quickly
through related topics.
 Decision trees help users to make complex
decisions by asking them simple questions
that can be answered with yes or no.
 Wizards help users to answer a complex
question by asking them simple questions and
guiding them to the answer that suits their
personal situation and context.
 Faceted searches narrow down search results
by providing contextual aspects that filter the
results of search actions.
13
Non-hierarchical navigation
As technical communicators, we are used to
structuring the content of our documentation
through chapters, sections and subsections.
On websites, we often find similar hierarchical
structures. For example, the website shown in
Figure 1 has six sections, each of which contains
information on a particular theme. The advantage
of this approach is that we offer our users a
straightforward path to the information that
we think is relevant to their goals. However, the
risk is that they may lose track of their position
within the structure when they reach the most
detailed information and then find it difficult to
change to an alternative navigation path.
On a website with a hierarchical structure,
relations of the type sub theme of relate all content
elements to each other (Figure 2). Hierarchical
navigation gives users the relative freedom of
choosing their own path, whereas serial navigation
would guide them step-by-step through a
process. For this reason, you find a combination
of hierarchical and serial navigation on more
and more commercial websites (Figure 3). Often,
the top levels of the structure are hierarchical
but the lowest level stimulates users to follow a
serial path (usually ending in a transaction).
With the use of semantic technology, we can
expand the number of relationship types within
a navigational structure, enabling users to
choose their paths depending on their goals and
context (Figure 4). Suggested relationship types in
addition to sub theme of and followed by are:
 Is part of to show how components are
related to a main product
 Is required by to show dependencies between
products or components
 Is excluded by to show that products or
components cannot be combined
 Is implied by to show that using one product
or component automatically leads to using
another as well.
Figure 2. Example of a hierarchical structure
Figure 3. A combination of a hierarchical and a serial structure
Decision trees
While non-hierarchical navigation gives technical
communicators more ways to express the
relationships between content elements, it is
still up to users to find out which path to follow.
In other words, we give our users the freedom to
gather the information needed to find out if, for
instance, a product, rule or law applies to them.
By providing a decision tree structure, we not
only save our users time but we can also make
their decisions uniform and reproducible.
The decision tree shown in Figure 5 helps users
to determine whether Investment Fund ‘X’ is
suitable for a customer. Depending on the answers
that the user gives, either a positive advice (Yes)
or a negative advice (No) will be presented. In
cases where a question is still too complex to be
answered without help, you can make the outcome
of the question dependent on the answers to
underlying questions. For example, if the user
Figure 4. Example of non-hierarchical navigation (investors risk profile)
cannot decide whether the ‘Customer has an
income’, clicking the + symbol displays three
more questions about the customer’s situation
that will result in a positive or negative response
to the statement about income.
Adding a decision tree to their intranet
website helps organisations to improve their
internal processes and enhance the integrity of
the decisions made. By adding the same decision
14 Methods
Figure 5. Example of a decision tree
and expected term of the investment, they can
limit the results to investments that fit their
personal needs.
Faceted searches can also be used on serviceoriented websites of product suppliers, where
customers can search for specific instructions
on specific products or components. The
Dutch Government uses faceted searches
to guide citizens from a search page on
any governmental website to the required
information, taking into account their personal
situation and the context of their questions.
Using a semantic toolset
Figure 6. Example of a wizard
References
Horton, W (2nd edn, 1994)
Designing and writing online
documentation. John Wiley
and Sons, New York.
Hughes, M (2002) ‘Moving
from Information Transfer
to Knowledge Creation: A
New Value Proposition for
Technical Communicators’
Technical Communication
49, no 3: 275–285.
Kees van Mansom MISTC
is a business consultant at
Be Value, a Dutch company
specialising in supporting
knowledge workers, and
has a background in
technical communication.
He presented a method
for developing knowledge
solutions at the ISTC’s 2006
Conference in London
and case studies on
knowledge-driven intranet
design at the STC’s 2007
Conference in Minneapolis.
E: kvanmansom
@be-value.nl
W: www.be-value.nl
tree to their Internet website, organisations can
make their processes clear to their customers
and provide facilities for self-service.
Wizards
Users sometimes visit websites looking for
answers to complex questions that cannot be
answered with a simple ‘yes’ or ‘no’. By using a
wizard, you can guide them through the steps
needed to answer such questions.
For example, consider a wizard for defining
financial risk. To assess risk, we need to know the:
1. Accepted balance between effectiveness and risk
2. Risk the customer is willing to take
3. Term of the investment.
These are all questions that the user is capable
of answering. Question 3 is only relevant if the
answers to questions 1 and 2 indicate that the
customer is willing to take some risk. Selecting a
short-term investment will then result in a more
defensive profile.
Using wizards to help users to answer
complex questions is an excellent way to
improve a website’s effectiveness. On a productsupport website, wizards might be used to help
users in problem solving or to find out which
product they have. They can also be used to help
users with calculations.
Faceted search
Search engines tend to offer users more results
then they can handle. Users have to browse
through all the results to find the relevant ones.
Faceted searches add the option to filter search
results on predefined context aspects. This
means that, for example, we can use the same
options that we used in the wizard for defining
the financial risk profile of a customer (Figure 5)
to filter search results.
When users search for ‘investment
opportunities’ on the website of a financial
institute, they will probably find a long list of
possible investments. By filtering these results
on accepted balance between effectiveness and
risk, the level of risk they are prepared to take
Creating a knowledge-driven website requires
a toolset that supports the modelling of
information and the creation of the solutions
described in this article. Although solutions
can be created in plain XML, using a tool that
supports drag-and-drop functionality makes the
creation and maintenance of models easier.
In my recent projects, I have used Be
Informed, a software suite that includes a
graphic editor with which to develop, manage
and maintain semantic models and metadata
structures. By applying instruments for
reasoning, comparing, deciding or calculating on
the semantic models, you can create a variety of
knowledge solutions.
Some final thoughts
In my presentation ‘Making knowledge
usable’ at the ISTC’s 2006 Conference we
looked closely at the possibilities of using
semantic technology for organisations, users
and technical communicators. At this year’s
Conference, I will explain how we can develop
these knowledge solutions and demonstrate
this with Be Informed, the tool set that we
use. As I will demonstrate, the development of
these knowledge solutions is simply a matter
of drawing the information models and linking
them to the available information. It needs
no programming but instead requires us to
think in information structures and to evaluate
carefully the way we present information to
our users, activities that we — as technical
communicators — do best!
I would like to conclude with an open
invitation to all of you to join me and my
colleague Menno van Rijk at the Conference in
Liverpool to discuss the possibilities of a
knowledge-driven approach in your own
working situation. C
15
Tools
InDesign CS3 versus FrameMaker 7.x
Philip Odell takes a look at some of the new long document
features in Adobe’s latest release of InDesign.
Once InDesign started to make serious inroads into
the publishing market, people who were looking
for a new DTP solution began asking me whether
they should embrace FrameMaker or InDesign.
Depending on the type of documentation they
wanted to create, my answer was always pretty
clear in favour of one product or the other.
However, with the release of InDesign CS3, those
clear distinctions have become a little more blurred.
Since the release of InDesign v2.0 (as distinct from
CS2), several long document features have become
available, namely: table creation, book building,
TOC and index creation and footnotes. Despite
this, the inability to create simple and multi-level
numbered lists, insert running headers/footers
and other variables has prevented InDesign being
considered a serious alternative to FrameMaker.
This has now been addressed in the new version
and this article is intended to contrast and compare
these new features with those of FrameMaker.
Being able to give each variable a more meaningful
name is a nice addition and the selection of
the first or last occurrence of a paragraph
from the Use menu is a little easier than the
<$paratext[+,paratag]> coding in FrameMaker.
The Type menu also offers a Running
Header (Character Style) option. This is similar
to FrameMaker’s Header/Footer $1 and $2
markers whereby text that does not appear
in a paragraph of its own can be inserted into
a header or footer. Although this provides
limitless options rather than just the two
markers offered by FrameMaker, only text that
has been tagged with a character style can be
used, whereas FrameMaker permits custom text
to be entered into the marker.
Variables
Figure 1 shows the interface and the variables
now offered by InDesign. Like FrameMaker, all
variables can be edited to control the display
of the data but InDesign provides the flexibility
of allowing the creation of several different
variables based on the same variable type. For
example, rather than having just Creation Date
(Long) and (Short) as in FrameMaker, you can
create additional versions and format them all
differently.
Chapter Number and Last Page Number are
comparable to FrameMaker’s Chapter Number
and Page Count. But because InDesign permits
a document to be split into sections and
numbered accordingly, Last Page Number has
an option to specify the scope of the variable,
which can be set to either Section or Document.
The equivalent of FrameMaker’s Current Page #
has always been available and is located under
Type > Insert Special Character > Markers.
The File Name variable offers the refinement
of selectively dropping the file extension,
and in the case of variables where text can be
added manually, special characters like em and
en spaces can be accessed from a sub-menu
rather than having to remember, or look up,
the character sequence. Unfortunately however,
double-clicking a variable in InDesign doesn’t
automatically display the variable interface.
Until now, the closest InDesign has come to
automatically inserting any text into a header or
footer was to use section markers. True Running
H/F’s are now available and the options for
creating them are shown in Figure 2.
Figure 1. InDesign’s new variable interface
Figure 2. Options for running headers and footers
16 Tools
Numbered lists
Being able to create and easily control simple
and multi-level numbered lists has long been
one of FrameMaker’s strengths and has often
been cited to me as one of the key reasons
people have migrated to FrameMaker from other
packages. Until now InDesign has fallen short
in this area but CS3 has given us something
akin to FrameMaker’s control. The Bullets and
Numbering panel in InDesign’s styling dialog
box are shown in Figure 3.
Having set the List Type to Numbers, you can
begin creating your list including setting up the
indents (hanging or otherwise) within the same
panel, which is convenient. One small point
worth mentioning here about hanging indents is
that InDesign requires the left indent value to be
matched with an equal negative first line indent
rather than a zero.
The creation of independent numbering streams
for tables and figures is achieved using the New
List command from the List option drop-down
menu (beneath List Type) and is comparable to
FrameMaker’s series labels. The option enables
you to give the list a meaningful name and
determine how numbering is handled across
stories or previous documents within a book.
A multi-level list is created by increasing
the value in the Level box. When this value is
Sub-menus providing access
to special characters and
number placeholders
Figure 3. Bullets and Numbering panel in the Paragraph Style Options dialog
H:Section <$chapnum>< =0>< =0>< =0>
H:<$chapnum>.<n+>< >< >
H:Figure <$chapnum>< >–<n+>< >
H:Table <$chapnum>< >< >–<n+>
Figure 4. Basing autonumbering on section numbers in FrameMaker
greater than one, the Restart Numbers at this
Level After: option becomes active (which is the
same as FrameMaker’s < =0> building block).
The Format field allows the use of upper and
lower case alphabetic and Roman style numbers but
also includes Arabic numbers prefixed by a zero.
The Mode drop-down performs a similar function
to FrameMaker’s <n+> and <n=1> building blocks.
The coding of a list itself is created in the Number
field, and like FrameMaker you can use a mixture
of text, punctuation, special characters and number
placeholders; the latter two being accessed from submenus by clicking on the arrow circled in Figure 3.
Once you get your head out of FrameMaker mode,
the implementation is relatively straightforward and
similar to FrameMaker in many ways, but it does
lack one feature. The piece of FrameMaker coding
shown in Figure 4 which allows other lists to be
based on section numbers using a single series
label appears not to be possible in InDesign.
To understand more fully the setting up of a
multi-level list in InDesign, the example in Figure 5
on the next page shows how a chapter heading,
sub-headings plus a figure would be coded.
Tables
Creating tables in InDesign has been possible
since version two, but until now you simply had
to copy a table from one place to another if you
wanted a similar style. With CS3 you can now
create and store table styles in a similar way to
FrameMaker. One difference however is that you
can also create cell styles. These can include
formatting such as cell insets, paragraph styles,
strokes and fills. Once a table has been created,
the cell styles can then be applied to different
regions of the table: header and footer rows,
body rows and left and right columns. This
provides a good deal of flexibility since the same
cell styles can be used in different table designs.
Like FrameMaker’s Update All, after editing
a style, all tables or cells to which the style is
applied are updated automatically.
Other long document features
It has been possible for some time to build books,
tables of contents (TOCs), indexes (or indices) and
insert footnotes in InDesign documents. In light of
this I felt it appropriate to mention these and point
out in general terms some of the pros and cons
between the products in relation to these features.
Books
InDesign’s book palette works much like
FrameMaker’s in respect of adding documents
and controlling numbering, pagination and
output. Book-wide updates, equivalent to
FrameMaker’s File > Import > Formats, is
achieved by designating one of the documents
in the book as the Style Source and then using
the book synchronisation command. FrameMaker
however scores over InDesign here in the way it
allows master pages to be linked to paragraph
17
Chapter 1 Heniam quiscilisi
Pat nit atie tate velestrud magniam illa cons at lutpat
nim zzriusci tionsed mod exer sed modolore commy
The word Chapter has been typed in. The (^H) is the
Chapnum placeholder and (^t) is a tab.
1.1 Ibh ex et, sit, sum autat
Ex erat. Ut nulla accum del in venissi sciduisit
1.1.1 Ostrud mod duissi
Riustie ming exeros nos adio od essi tem
venis enisi eugait.
The first level heading (1.1) inherits the Chapnum (^H). The
placeholder (^#) represents the current number level which
has been set to 2 in the Level box and is followed by a tab.
Figure 1–1 Wisi blan venibh ea ad tem
Figure has been typed in followed by the Chapnum (^H),
then an En Dash (^=), then the current level (^#) and a tab.
The second level heading (1.1.1) inherits the Chapnum (^H),
the (^2) represents the level number of the first level heading,
this is followed by the current number level (^#) set to 3 then
a tab. This number is also tagged with the Emphasis style
Figure 5. Example of a multi-level list and the associated coding in InDesign
formats and then have the master pages
automatically applied.
TOCs and other lists
Creating generated lists in InDesign is a
little more flexible than in FrameMaker.
Firstly, all of the set up for styling the TOC
entries — including the numbers and tab
leaders — can be accomplished in one TOC
creation dialog and stored for subsequent use.
InDesign now also provides commands equivalent
to FrameMaker’s <$paratext>, <$paranum> and
<$paranumonly> building blocks to allow selective
extraction of data. Secondly, you can easily flow a list
of tables and figures after a list of contents without
the need for importing other files by reference.
You can’t however create a list of paragraphs or
markers.
Indexes and footnotes
Like FrameMaker, index coding in InDesign is
labour intensive, but flexibility is again the key word.
Topic lists from other InDesign documents can be
imported, all occurrences of an entry can be created
quickly and easily at one time, and like TOCs, the
set-up and coding can all be accomplished in
one dialog box. The same is true of Footnotes
too. The coding and control is comparable to
FrameMaker but all set up including ruling
line offset, colour, line style and width can be
accomplished together.
Other features
InDesign doesn’t have a cross-referencing
feature, neither can it handle conditional
text nor implement a sidehead layout in the
way FrameMaker does. However, InDesign’s
typographical control is considerably greater,
and the ability to import native layered
PhotoShop (.psd) and Illustrator (.ai) files and
control the visibility of the layers on the page
is a nice addition. This offers the flexibility
of having several representations of the same
linked graphic.
The concept of styling objects (introduced
in InDesign CS2) is a great productivity
enhancement too. Basically anything you can do
to an object — applying fills, strokes, text frame
options and other effects — can be stored as a
style and quickly applied to any other object.
This is particularly useful when a graphic
needs to be anchored at a specific position
from within the text flow. InDesign has always
allowed graphics to be placed inline, which is
comparable to FrameMaker’s at insertion point
option, but now you can not only specify the
precise anchoring position of any object, but you
can also store this anchoring attribute as part
of an object style ensuring that the placement
of your graphics is consistent. The anchoring
option permits objects to be positioned outside
of a text frame as well.
Summary
There are many other comparisons that could be
made of course and I realise that XML has not
been mentioned either, but it was not the
intention of this article to go down that route.
However, I hope it has served its intended
purpose and will prove a useful source of
information for anyone contemplating a move to
a new DTP solution. C
Philip Odell is a freelance
trainer and consultant
specialising in Adobe’s
Creative Suite products
and FrameMaker. Philip’s
clients range from
individuals to corporate
organisations. He also
works for Adobe on
a freelance basis at
exhibitions as a presenter
and demo artist. Recent
events have included
IPEX, Print Expo and
Adobe Roadshows.
W: www.philipodell.co.uk
18 Project profile
Faster, cheaper, better documentation
Karl Darr describes how BMW Motorrad engaged the STAR Group
to assist in implementing a new technical editing system.
Today’s customers of BMW Motorrad (German for
motorcycle) expect a range of product variations
with different designs and numerous options for
special equipment and accessories. BMW Motorrad
accommodates the increasing demand for
individuality, not only in its visions and designs
but also in all of its related documentation.
This is achieved using modular authoring
techniques. The newly implemented system, TERES
(TEchnisches REdaktions-System — German for
technical editing system), supports the core elements
of modularisation, structure and version control.
The idea is to synchronise product engineering
processes with information creation processes to
produce consistently high-quality documentation.
Previously, BMW Motorrad’s documentation
was created and published using a combination
of Interleaf, FrameMaker and Microsoft Word.
Today, all of its technical documents are
generated internally, published on various media
in German and, depending on document type,
up to 12 other languages.
Provide more languages in response to new
market penetration
Ship information in the right language at the
same time as the product (known as ‘simship’)
Reduce the time and cost associated with
translation, data preparation and quality
assurance.
Requirements for the new system included:
Media-neutral data management based on
XML/SGML technology
Flexible reuse of information units (IUs)
Synchronised working in a geographically
distributed team, over internal and external
networks
Integrated language and translation
management, including an interface to an
XML/SGML-enabled translation memory
system and the ability to translate only
changed information
Varied search features (for example, full text,
metadata and tag search)
Role-based user access authorisation to
optimise the editorial workflow
Version management
Management of non-XML formats (such as
graphic and PDF files)
Integrated workflow and reporting
management.
BMW recognised that the existing system could
not address the new requirements and so a new
system was essential. As well as achieving high
quality, three further benefits were sought:
Shorter production cycles and processing times
 Lower costs, particularly for layout work
 Efficient use of content, avoiding the time and
errors associated with duplicated text.
Guidelines
Figure 1. US variant of the Rider’s Manual for the R 1200 GS motorcycle
Requirements
In moving from the existing system, BMW
Motorrad needed to:
Improve data quality
Accommodate growing product complexity
(and therefore document volumes) and over
150 motorcycle variants (example in Figure 1)
Extend the life of documents
Having experienced difficulties with other
document and content management systems,
which increased time and cost pressures, BMW
Motorrad defined strict guidelines for the new
solution. These specified:
Fast implementation of the new hardware and
software to deliver fast return on investment
No disruption to production, with existing
processes and provisioning targets protected
Integration into the existing IT infrastructure
Less time spent on editing, translation and
publication
More time spent on researching content
Reuse of information in different types of
documents
Structured data management
Migration and reuse of legacy data
Use of the delta principle (described opposite).
19
Figure 2. GRIPS Matrix 4-dimensional database
From concept to solution
Based on the newly defined requirements and
goals, BMW Motorrad decided to implement
a solution from the STAR Group. The TERES
solution uses four STAR systems:
GRIPS for information management
Transit XV for translation memory
TermStar XV and WebTerm 6 for terminology
management.
GRIPS
GRIPS (Globales Redaktions- und InformationsPlanungs-System — German for global editing
and information planning system) is a databasetype integrated system for the structured entry,
management and publication of multilingual
information (Figure 2). Based on SGML/XML, it
is a transparent management system for storing
self-contained IUs to be used in single-sourced
documentation. IUs can be managed and
used more than once by linking, which avoids
redundancy and records interconnections.
This approach enables on-demand, automatic
production of derivative documentation. For
example, a Quick Start Guide may be derived
from an Owner’s Manual, which is derived
from a Maintenance and Repair Manual,
which is derived from the original engineering
documentation.
A typical example from the automotive world
would be the IU that describes an assembly
sequence. This is linked to the IU for a tool that
is required for a specific assembly operation.
Each of the two IUs is self-contained in terms
of content. The assembly instructions describe
all the required operations in the assembly
sequence and the tool description contains all
the technical details of a particular tool. With
the link, the tool data can be accessed from
the assembly instructions and, in the tool
description, there is a reference to a practical
use for the tool showing what it is required for.
GRIPS is based on:
The delta principle
IU structure and management
Separation of content and layout.
The delta principle
Delta means difference: technical writers and
translators only work on new data that is different
from the old version. The same information, and its
translation, is reused automatically in documenting
new products and variants. This delivers time
and cost savings, as well as higher quality.
20 Project profile
Figure 3. GRIPS Editor enables writers to capture content in semantic data structures,
while GRIPS MindReader controls terminology and proposes words and sentences.
IU structure and management
Effective management and maintenance of
information can be achieved by careful subdivision
into IUs with self-contained content, as described
for the automotive example. Each IU can be
allocated to a particular class of information,
referred to as an information type. Each
information type has a typical content structure,
specified by an information type definition.
This achieves transparent modularisation of the
database using logically comprehensible modules.
Information entry is independent of layout.
An information item is made up of logically
self-contained information components. The
benefits of this working method far outweigh
the inconvenience of the changeover:
Information can be entered at the point of
origination. This ensures high levels of data
immediacy and quality as transposition
errors are virtually eliminated. The use of a
defined content structure standardises the
information entered.
IUs can be updated or modified independently
of one another, which means that they are edited
only when their content changes. The significance
of an IU within the database is always clear.
IUs can be linked to form an information
network and reused as many times as
required. The duplications typical of other
document management systems can be
minimised or even eliminated.
Content-related identification of individual
information components lends the database
intelligence, facilitating subsequent
automated processing. IUs can be managed by
information type, product structure, product
variant and language.
Separation of content and layout
As explained, information entry is independent
of the final document format. GRIPS starts
the information life cycle from an engineering
perspective, with data entered into pre-defined
structures (Figure 3). At publishing time, it
processes the data automatically into different
document types in various languages and media,
without manual intervention. Product- and
customer-specific documents can be generated and
published on demand, all from a single source.
For special product configurations, TERES
can generate machine-specific and equipmentdependent documents (Figure 4). Using filters,
repair manuals can be generated for product
variants. For example, a certain equipment feature
such as an existing anti-lock braking system may
be selected. The repair manual is automatically
adjusted to include additional work steps such
as ‘change of brake fluid’ or ‘removal of tyres’.
The classified, structured and centralised
approach to data management enables
mechanics to retrieve more task-related
information dynamically for particular work
steps or for entire work processes (for example,
all related and required tools, lubricants and
technical data). TERES also supports dynamic
generation of machine-related maintenance
plans based on motorcycle type, past driving
performance or vehicle use.
Reaction from technical writers
Figure 4. The content of Figure 3 used in the BMW Rider’s Manual
Despite experience of structured authoring,
the technical writers at BMW Motorrad initially
brought some book-based concepts to the
new processes. Now, however, they no longer
write any documents into a book structure but
instead, following strict guidelines, enter data
into pre-defined information structures.
ads_uk.qxd
Karl Darr is an independent consultant for content
management solutions.
Why
not change the approach for the benefit of all?
The information analysts and engineers at STAR specialise in
developing information models that represent the company's
intellectual assets, similar to the way a product is developed.
Thus, technical writing becomes straightforward.
Coming at the technical publications market from a translation
perspective, STAR has solved the most vexing problems that
usually arise in conventional document management and publishing systems.
Take advantage of STAR's experience and software solutions to
develop an information model specific to your company.
Enable company-wide creation, management and updating of
technical information from a single source. Ensure fully-automatic user and application-specific publication in all languages for any media.
at the Core
n
o
ti ing Knowledge Ma
mangineer
r
o on E
i
nag
em
en
t
r
Te
The new system delivered the benefits that BMW
Motorrad had identified:
 Cost savings
The integration of language and translation
management, as well as the filter function for
delta translations, reduced overall translation
costs by about 20%. The flexible reuse of IUs
and the ability to collaborate globally reduced
documentation costs by 40%.
 Time savings
The consistent structure of information types
guarantees a standardised level of content. This
reduces research, search and entry time, and
accelerates the production of documentation.
 Better data management
Textually classified, structured and centralised
information produces more documents in less time,
with greater depth of detail and higher quality.
 Greater flexibility
BMW Motorrad can produce product- and
user-specific information in all languages
for all media. It can respond quickly to
product innovations, such as interactive
documentation, diagnostic systems or
information retrieval through any mobile
device. Demand for integrating more types of
documents is constantly growing. Different
departments can use the same high-quality
data, combined to suit their individual needs.
Working with the GRIPS information management
system, the TERES solution has become more than
an information management system. It is a
knowledge database, where inter-divisional
intellectual assets are managed, retrieved and
consulted. BMW Motorrad is more prepared than
ever to develop its documents in any direction
that its customers require. C
21
Seite 1
lat
ion
Results of implementation
12:36
Inf I
orm n
at f
The system provides for automatic reuse
of IUs for new products or variants wherever
possible. Consequently, the writers enter
only new data and reuse existing information
to create new vehicle-specific documents.
Thus, they are able to focus on what they do
best — creative technical writing — without
having to worry about time-consuming layout
and formatting work.
19.03.2007
m
ino
log
y
Auto
mation
Established in 1984, the STAR
Group is globally recognised as a
leader in information management, globalisation, internationalisation, and localisation solutions as well as a premier developer of language technologies.
With 22 years of experience and
a staff of 1000+ language and
technology experts located at 39
offices in 29 countries, the STAR
Group is the world's largest privately-owned translation technology and services company. In
tion
Publica
ns
Tra
fact, STAR is the only language
service provider to have created
all of the technologies necessary
to effectively manage all phases
of technical publication.
STAR UK Limited
Network House, Bradfield Close
Woking, Surrey GU22 7RE
Phone: 01483 242 480
Fax: 01483 242 479
E-mail: [email protected]
www.star-group.net
22 Tools
Review of the MadPak authoring suite
Matthew Ellison explores the content of
MadCap Software’s latest suite of products.
Introduction
Flare’s interface
MadCap MadPak is an integrated suite of tools
that is designed to meet the needs of authors
creating software user assistance. It has been
developed by MadCap Software, a San Diegobased company formed in 2005 by a group of
people who had previously worked on RoboHelp
for eHelp Corporation and Macromedia.
The suite is based around Flare, MadCap’s
Help authoring tool and flagship product,
version 1.0 of which was reviewed by Carol
Johnston in Communicator Summer 2006.
Version 3.0 was released this summer and,
within the MadPak suite, it is complemented by
three other tools: Mimic, Capture and Echo.
In this article, I review the complete MadPak
suite of products. When dealing with Flare, I have
chosen to focus particularly on features added
since version 1.0. I also comment on the level of
integration between each of the products.
In common with other modern authoring tools and
Integrated Development Environments (IDEs), Flare
has a customisable multi-pane interface. You can
edit multiple topics simultaneously, and each topic
is displayed in its own separate window pane.
In addition to that, there are numerous window
panes that are used for a variety of purposes
including Project Explorer, File List, Styles and
Index Entries. Even the Help for Flare itself is
displayed within multiple window panes that are
embedded within the user interface. Overall, this
makes for a complex interface that can be a little
overwhelming for new users of the product. I’d
recommend that all Flare users invest in a highresolution monitor to enable them to organise and
manage the window panes more effectively.
Flare 3.0
Flare is a relatively new Help authoring tool that
first appeared on the market in March 2006.
MadCap Software claims that its lack of longevity
is actually one of the product’s greatest strengths
because the developers have not had to deal with
the issue of outdated legacy code. Flare has been
developed from scratch in C# with the needs of
the modern-day Help author in mind, and with
all its project files (including topic content) being
strictly XML compliant. Since version 2.0 it has
also been fully Unicode compliant, supporting
a wide range of languages (including Asian
double-byte) from a single interface.
Another of Flare’s key strengths is its
impressive range of single-sourcing capabilities.
Single-sourcing means different things to
different people but, as a minimum, it means
being able to generate output in a range of
different formats (onscreen and print-oriented)
from the same source project, with the potential
to exclude specific content from each of the
different output types.
Flare can certainly do this: although
primarily a Help authoring tool, it is also
capable of generating print-oriented output
in either Word (2003 or 2007) or FrameMaker
formats. However, it takes single-sourcing and
information reuse to another level with a range
of advanced features such as snippets (that
enable you to insert the same chunk of content
by reference within multiple topics), condition
tags that can be applied to almost any project
element, media-specific formatting and crossreference formats, and multiple TOCs.
Topic editing and formatting
Topics are created and edited using Flare’s XML
Editor. Although XML-based, Flare does not
allow you to edit any XML variant of your own
choosing — topic content must be coded in XHTML,
a mark-up language that conforms to strict XML
syntax but has the same depth of expression as
HTML. The XML Editor is quite easy to use and has
a number of very powerful hidden features, most
of which are available from pop-up menus that
appear when you click on parts of the content. For
example, you can easily select and move blocks of
text, and you can sort list items automatically.
You format content by applying combinations
of XHTML elements and CSS classes (for example,
p.Warning, h1.Special, li.Step), and Flare provides
a Stylesheet Editor for defining the CSS properties
for each of these elements and classes. Novices
who have been shielded from the technical details
of CSS by previous authoring tools may find the
Stylesheet Editor quite challenging. In response to
feedback, MadCap has introduced a Simplified View
in version 3.0 but, in my opinion, even this requires
some understanding of CSS properties and values.
Source control integration
This new feature in version 3.0 enables you to
integrate Flare with Microsoft Visual SourceSafe,
Microsoft Team Foundation Server or any other
source control tool that supports the Microsoft
Source Code Control Application Program
Interface (SCC API).
Flare’s source control integration means that
you can do all your source control tasks (such as
adding a project to source control, checking files in
and out, and viewing file history) from within the
Flare user interface. What is more, Flare provides
you with a number of useful prompts that help to
23
ensure that the project in source control is kept
up to date. For example, when you close a project,
Flare informs you if you still have files checked
out (Figure 1) but it does not automatically list
these for you, which might have been useful.
One of the key benefits of source control
integration is that it enables multiple authors
to work on the same Flare project concurrently.
Each author has a local copy of the project and
checks out files from a server-based source control
database as required. This system prevents authors
from inadvertently over-writing each other’s work.
WebHelp Plus
New in version 3.0, WebHelp Plus is an extension
of the browser-based WebHelp output in earlier
versions. It enables users to search a range
of non-XHTML file types (including PDF and
Microsoft Word) that can be deployed with the
ordinary XHTML-based Help topics. WebHelp
Plus also offers faster searching and automatic
merging of outputs from multiple projects (which
otherwise would require the creation of a ‘master’
project). WebHelp Plus must be deployed on a
server running Windows XP or Windows Server
2003, and also requires Internet Information Server
(IIS) and ASP.NET — it can’t be hosted on Vista.
This provides the potential for Help to become
the ‘one-stop shop’ for all information including
not only the ‘official’ author-provided instructions
but also the community-based tips, opinions, and
experiences. The feedback service also enables
you to track which topics your users are looking
at, and (for all Help formats except HTML Help) to
report on search phrases that users have entered.
However, all these benefits require additional
financial investment. To implement the feedback in
your Help, you must set up a server-based service
that will receive and store the feedback data. You
have the option of paying to use a service hosted
by MadCap Software on its own servers, or you
can purchase the required Feedback Server
software to run on your own hardware.
FrameMaker import
The ability to import FrameMaker documents into
Flare, mapping styles in the process, was added
in version 2.0. It includes a feature called ‘Easy
sync’ in MadCap’s marketing literature but, less
snappily, ‘Auto re-import before Generate Output’
in the user interface. It means that, after importing
a FrameMaker document, you have the option to
re-import the document automatically if it has
changed (refreshing the topics that were imported
previously) each time you generate the output.
The advantage is that you can continue to update
your FrameMaker document, treating it as your
single source for both print and Help output. The
downside, of course, is that by re-importing topic
content from FrameMaker you lose any changes
that you may have made to the content in Flare.
To help you maximise the value of your
FrameMaker content, MadCap has added
in version 3.0 the ability to insert special
markers and styles within FrameMaker that
map automatically to features within Flare. For
example, there are two styles for identifying dropdown hotspots and associated drop-down text.
These markers reduce the need to work on topics
in Flare after they have been imported, and make
the Easy Sync feature more viable and useful.
Feedback
Flare 3.0 introduces a feedback feature that enables
users to comment on Help topics. These comments
can be submitted either to the author of the Help or
to all other users of the Help (for example, to share a
useful tip or idea). This feedback service is available
for all Flare’s Help formats, including HTML Help.
Figure 1. Warning that files are open when closing a project in Flare
Mimic
Mimic enables you to create demonstrations and
interactive tutorials that can include captions, audio
and a range of visual effects. Typically, you record a
task by capturing screenshots at key instants of the
procedure, edit and enhance the resulting ‘frames’
within the Mimic Workspace, and then publish the
resulting ‘movie’ to a format that users can view.
Intended specifically for creating software demon
strations and simulations, Mimic does not purport
to be a general eLearning tool and so it provides no
support for integration with Learning Management
Systems and no facility for creating quiz questions.
However, it has some interesting unique features.
Mimic offers two possible output formats, Adobe
Flash or its own unique MadCap Mimic movie
format. The advantage of the latter is that you can
compress movies into files significantly smaller
than the Flash equivalents. However, the Mimic
format requires users to have either MadCap
Movie Viewer or MadCap Help Viewer (both of
which are freely distributable) installed on their
computer. For that reason, if you are deploying
your Mimic movies on the Internet, MadCap
recommends you use the Adobe Flash format.
24 Tools
capture within a Help topic in Flare, Flare selects
the appropriate version of the image at generation
time, depending on the medium of the output.
MadCap Capture excels at annotating
and editing captured images. It provides a
comprehensive range of vector-based drawing
tools and objects, and even enables you to
combine two different bitmap images while
keeping each of them on a separate layer so that
they can be independently edited or replaced.
At a more basic level, however, I do miss the
magnified view of the screen area around the
mouse pointer during region captures that other
screen capture tools provide.
Echo
Figure 2. Multiple-pane working environment in Mimic
Mimic gives you the option to package multiple
movies together within a single project. This
enables you to perform tasks (such as publishing)
on the entire set of the movies in a single operation.
It also makes it easier to integrate the movies more
tightly together at playback time, for example
enabling the user to select the required movie from
a drop-down menu containing the entire set.
Mimic shares the same user interface paradigm
as Flare (and indeed all the other tools in the
MadPak suite), and its Workspace consists of
numerous window panes (Figure 2). New users who
are familiar with other software demonstration
tools may find it quite difficult to adjust to this
paradigm and to Mimic’s way of implementing
various movie features. In particular, I found
mouse trajectories rather challenging to work
with when I started out. However, the ‘How to
Create Movies’ tutorial (available from Mimic’s
Getting Started Wizard) demonstrates that it is
possible to create very impressive results.
Capture
Matthew Ellison has
20 years of experience
as a trainer and user
assistance professional
in the software industry.
He now runs his own
independent UK-based
training and consulting
company that specialises
in online Help design
and technology.
E: matthew
@ellisonconsulting.com
W: www.
ellisonconsulting.com
MadCap Capture enables you to capture
individual screens, and to apply a range of
callouts and effects to the resulting images.
Its capture ‘profiles’ enable you to save named
collections of capture settings for future use.
One of the key features that distinguish
MadCap Capture from other screen capture
products is its support for ‘recapturing’ regions
using precisely the same screen coordinates as
used by the original capture. This enables you to
recapture a region that was originally captured
perhaps days or months earlier.
MadCap Capture also enables you to ‘singlesource’ two different images from one capture.
You can provide one group of settings for Help
output and another group of settings for print
output, and this information is stored alongside
each captured image. When you insert the screen
Echo is a small application that enables you
to add sound to any HTML page. The sound
is encapsulated into a Flash (.swf) file with a
toolbar for controlling the sound playback. This
toolbar can also incorporate links to an image
(for example, a logo) and to a web page.
Echo provides controls for recording the
required sound, and doing simple editing tasks
such as adding silence and boosting the volume.
Integration of the MadPak products
As you might expect with a product suite of this
type, each of the three subsidiary tools (Mimic,
Capture and Echo) can be launched in a variety
of ways from within the Flare interface, and there
are commands for inserting Mimic movies, Echo
audio files, and Capture images within Help topics.
However, the integration goes a step further, with
the complete suite providing more than the sum
of the individual parts. As an example, you benefit
from the single-sourcing capabilities of MadCap
Capture only when you include your captured
image within a Flare project.
Variables (such as product name or company
phone number) provide another example of tight
integration between the products. Variables
can be defined within a Flare project and then
referenced within either Mimic or Capture. Thus,
you can include variables within the captions in
your tutorials or within the annotations in your
screen captures, and then update the values of
these variables globally from within Flare. This
is a powerful feature that has the potential to
reduce maintenance costs.
Overall, the MadPak suite offers a complete
and complementary set of tools that share a
common user interface paradigm and integrate
well together. They provide an innovative set of
features, and are particularly strong on singlesourcing and information re-use. Be prepared,
however, for a fairly steep learning curve if you
want to get the most from these tools. C
26 Illustration
Using 3D data in technical illustrations
A summary of how technical illustrators use the wealth of information
in CAD files to illustrate manuals and more, from Matthew Jennings.
Ten years ago, the engineers with whom we
illustrators worked would supply us with all the
relevant engineering drawings in the form of
blueprints for a project. These days, we still work
with the same engineers but now they supply
us with a disk containing three-dimensional
computer-aided design (3D CAD) data of their
product. In this context, 3D data means an export
of a file from a CAD package into a standard data
format. Two common formats are STEP (STandard
for the Exchange of Product model data) and
IGES (Initial Graphics Exchange Specification).
Some might argue that the illustration game
became easier and now requires less expertise. I
would argue that the goal posts have merely shifted
in our technical illustration workflow.
Exploded black and white line
art illustrations are now only
considered the first stage in
our services, equivalent
to the typesetting
of a brochure in
a graphic design
studio. I say
this because
these are the
easy and less
creative stages of our
work, partly because
they have become highly
automated. CADprocess
by IsoDraw is responsible
for a large proportion
of the move towards
using 3D data. Because
‘bread and butter’ spare
parts illustrations can
be created relatively
quickly, this leaves
more in the budget for
the ‘luxurious’ projects
that were formerly the
domain of corporations
with bottomless
budgets. Typical projects
range from full-colour
perspective cutaways
and product
visualisations for
use in marketing
literature to
interactive media
projects requiring
animations and
programming skills to
bring the artwork to life.
Figure 1. Producing a colour cutaway
Many of the samples you see in this article are
achieved using a variety of skills and software
packages. It is rarely the case that one software
package can do everything well; all have their
strengths and weaknesses.
Photo-realistic images
The cover of this issue of Communicator shows a
transfer gearbox. The objective was to produce a
colour cutaway of the product for a new brochure
and exploded line drawings for the spare parts
and service manuals. So, how was it done?
Firstly, we were given a STEP file of the whole
assembly. This included all the parts, down to the last
nut and bolt. As the client requested a cutaway (see
Figure 1), we had to create the cuts in 3D CAD software
before rendering. We then created a low-resolution
render for client approval before proceeding.
Because we did this stage using parametric
modelling software, these cuts could easily be
moved until a satisfactory result was achieved.
At this point, the model consists purely of
three-dimensional objects in an undefined space
without any material attributes. Next, we have to
assign surface properties to the model, ranging
from shiny blue metallic paint to polished steel
gears.We did this by creating surface properties
that contain values representing attributes such
as colour, reflectivity, smoothness, specularity and
transparency. The more sophisticated your software,
the more control you will usually have over these
attributes to represent real-world surfaces. To
accentuate lighting and shininess, we also added
small fillets to many of the sharp corners in the
model. This creates an extra surface to reflect
the light, thereby giving highlights. Although
these fillets are not technically accurate, it makes
a massive difference to the three-dimensional
effect of the finished artwork. This is something
that could not be achieved in a photograph
without manipulation, where you would be at the
mercy of what the studio lighting could achieve.
To create this image we will be taking a ‘virtual
photograph’ of our model. This means we will have
to define a virtual studio to tell the software what
kind of lights, camera and environments will be
used. These attributes will have a major influence
on the end result and even small changes can make
a big difference. Therefore, a basic understanding
of how cameras and studio lighting work will go
a long way to achieving a photo-realistic image.
In this sample, we chose to have soft shadows
created by spotlights on a white floor (Figure 1)
and an image of an industrial space was used as
a environment map for creating reflections.
A small amount of perspective was given to add
27
Figure 2. Highlighting details in an illustration
Figure 4. Combining rendered
detail with linework context
Figure 3. Showing other surface finishes
realism, accentuate size and make the image more
striking. After all these details were addressed, we
proceeded to create a final render of the file. This
is where the computer generates a final image to
a high resolution to create a file that can be used
for many different purposes, from brochures to
websites. As well as creating a large image, often
up to A3 in size, the computer has to take into
consideration lighting, colour, texture properties
and reflections of the environment — that’s a
lot of pixels to work out! Consequently, it is not
uncommon for a render of this size and quality
to take 10–20 hours to create on an average
machine. For this reason, it is wise to render as
large as possible to cover for all possible uses.
Details may be later be extracted as shown in
Figure 2.
Figure 3 shows another example of photorealistic rendering, this time with a mottled finish
to represent a typical cast part. This level of realism
could easily be used in marketing literature when
CREATE QUALITY TECHNICAL ILLUSTRATIONS IN MINUTES
28 Illustration
Line illustrations
the hardware is not yet ready for photography,
enabling brochures to reach prospective purchasers
as soon as possible. In the case of cutaways like
the gearbox, 3D images can be more cost-effective
than photography: cutting actual gearboxes in
half is not a great investment!
Of course, 3D imagery does not have to be
realistic: it can be what ever you want. Figure 4
combines linework and rendering to put the focus
on the internal components and leave the casing
without colour. Real-world effects such as lights
can also be simulated to great effect, as shown
Figure 5. In this case, the product was not available
when the packaging was designed. Without a
functional prototype, the ‘on’ state could not be
photographed. This example also demonstrates
simulation of light sources. Two bright white
spotlights were created at the centre of the bulbs.
With the bulb surrounded by mirror-like parts, the
reflections created are realistic and easy to achieve.
3D data has not only changed the way in which we
produce colour cutaways. It has also had a major
effect on the creation of the most common type
of illustration, the exploded spare parts drawing
(Figure 6). Massive time savings are to be made in
these illustrations, to the point where the process
is almost automated and the illustrator applies the
finishing touches and corrects any anomalies. The
most common fault when creating line drawings
from 3D CAD data is that the linework produced is
not of sufficient quality. Examples include ellipses
made up of hundreds of small lines and small
template parts (such as bolts) having missing
threads or points between straight and curved
sections. A significant editing task is to remove the
contour lines that the CAD system uses to create
objects. Often, due to the high tolerance and detail
required in 3D CAD applications, the data contains
details that would not normally be drawn as they
67
12
10
68
11
66
9
74
8
72
71
7
6
69
5
4
73
3
70
2
20
Figure 5. Simulating photographs of
products before they are complete
19
65
18
77
64
17
76
16
1
15
110
30
14
109
75
31
29
13
79
78
28
27
108
107
106
26
105
104
103
102
25
101
24
100
99
97
23
98
50
96
48
46
45
44
22
94
91
90
95
41
21
40
93
81
92
39
80
47
62
60
59
83
84
85
49
37
82
33
43
32
57
42
86
63
55
54
61
52
38
87
88
89
35
36
58
34
56
53
51
Figure 6. Using exploded illustrations
to show the assembly of parts
Figure 7. Editing line illustrations:
before (left), after (right)
29
are so small and barely visible. Although these
lines are not incorrect, they clutter the illustration
and unnecessarily increase the file size. Figure 7
shows a line illustration before and after editing;
unwanted lines have been removed on the circular
plate, threads added to the bolts and lines
added to show how the parts fit together.
Many of the issues can be corrected with software
plug-ins and processes. IsoDraw CADprocess goes a
long way in this direction. In any event, the editing
stage is a small price to pay for the information
available from CAD models. Parts such as gears,
which were once the bane of every illustrator,
are now shown accurately in no time.
An important feature to note when using a
3D file as your information source is the ability
to show a part in different viewpoints. This is
most useful for service and installation manuals,
where the text instructs the user to position
a part in different orientations (for example,
vertical, horizontal or angled). In this case, we
can simply refer back to the original 3D software
and rotate the part into its new position. The ease
of creating new viewpoints enables illustrators to
produce more informative illustrations that show
exactly how procedures look at different stages.
This can only be a good thing for the quality of
manuals and their accompanying illustrations.
Animations
Having read this article, you might be forgiven for
thinking that technical illustration is becoming
an automated process that requires less skill and
creativity than in the past. This may sometimes be the
case — as we saw for exploded parts drawings — but
I believe the opposite is more often true.
The 3D CAD data we now receive is so
comprehensive in its content and so flexible to
work with that many more options are available.
An example of a modern option is animation
(Figure 8), which can be used in electronic manuals,
presentations and websites. While animation itself has
Figure 8. Showing movement using animation
been around for a long time, producing animations
in a technical illustration studio is relatively new. In
the past, modelling the physical parts of a product
would have accounted for more than half of the
time required. Now that we have the structure of
the product in the CAD file, we are already halfway
to creating an animation, thus putting animation
within reach of many more users and budgets.
In conclusion
Technical illustration has come a long way in the
last 15 years, with major advances in the way we
go about our work. For me, the future for technical
illustration based on 3D CAD data looks exciting
and promises endless opportunities to flex our
creative muscles. C
Have your cake and eat it!
“In-house” graphics without the expense
Technical Illustration On Demand
Matthew Jennings is
managing director and
practising technical
illustrator at Industrial
Artworks Ltd, an ISTC
Business Affiliate.
W: www.industrialartworks.co.uk
We appreciate the need for a cost effective, fast and
approachable illustration service you can call your own. From
a single colour cutaway to a complete manual, we have the
manpower, tools and experience to help you deliver your
project on time, in budget and to a high standard.
• 3D CAD Translation
• Product Visualisation
• Line Illustrations
• Exploded views
• Cutaway views
• Interactive Media
12
16
22
18
Industrial
Artworks
17
For a no obligation quote or just to chat about how we can
help give us a call on 01422 845505
[email protected] / or
www.industrial-artworks.co.uk
visit www.industrial-artworks.co.uk to view more samples.
30 Aviation
90 years of aircraft history
Passionate about his work, Gene Sexton explains why Boscombe
Down is a very special place to be a technical communicator.
With its long and esteemed history, Boscombe
Down, in Wiltshire, is a place of special interest
for aircraft enthusiasts the world over. It has
been the home of the world famous Empire Test
Pilots School since 1943 and has been testing
aircraft and their systems since 1939.
Boscombe Down first opened as an airfield in 1917,
equipped with Bristol BE2 biplanes, but returned to
its previous role as farmland after the First World
War. It would seem though, that the defence of the
realm and aviation were to be the site’s destiny.
Boscombe Down’s long association with
aircraft testing began when the then Aeroplane
and Armament Experimental Establishment
(A&AEE) first moved there in the August of 1939,
at the commencement of hostilities with Hitler’s
Germany. The move from Martlesham Heath in
Suffolk was made because of its proximity to the
east coast and vulnerability to enemy attack.
Now run by QinetiQ, Boscombe is no less
involved with aircraft testing and evaluation
than it was then. Testing and evaluation of new
aircraft systems in support of the MoD continues
unabated at what is arguably as stressful a time
for our armed forces as they have faced since
Bristol BE2 at Boscombe Down
the Second World War. There have been notable
conflicts in the intervening years but staffing levels
have never been lower and technology require
ments never higher, which means that QinetiQ’s
expertise in the design, test and evaluation of
defence equipment is as necessary now as it ever
was. I am extremely proud to be involved in that
work, patriotic old fool that I am!
Although best known for the Empire Test Pilots
School and the A&AEE, Boscombe Down has seen
several other key events in its 90-odd year history that
may interest Communicator readers. My intention is
to give a brief history of significant events at the site.
The early years
RAF Boscombe Down reopened in 1930 as the home
to 9 Squadron, flying Virginia heavy bombers, to be
followed the next year by 10 Squadron flying first
Hinaidis and subsequently Virginias and Heyfords.
There were various other comings and goings of
squadrons and aircraft in the years leading up to
the Second World War. Apart from being the new
home of the A&AEE, the airfield had other war duties.
Hurricane aircraft of 56 and 249 Squadrons operated
from Boscombe Down during the Battle of Britain.
Lancaster ED 825, made famous by The Dam Busters film
Boscombe Down airfield in 1918
Captured ME109 on test at Boscombe Down
31
Of particular note from that time is that the
only participant in the Battle of Britain to win the
Victoria Cross — in fact, Fighter Command’s only
Victoria Cross of the Second World War — flew his
249 Squadron Hurricane Mk 1 from Boscombe
Down. He was Flight Lieutenant J B Nicholson and
the excerpt shown in the panel describes the actions
that resulted in his award. Incredibly, he was able to
return to flying duties just eight months later after
recovering from his injuries, including a gunshot
wound to his buttocks inflicted by a local defence
force volunteer as he descended in his parachute!
Notwithstanding the dogfights, testing at Boscombe
continued unabated. The only aircraft entering
service that were not assessed by A&AEE were
flying boats and gliders, so it should be impossible
to name a Second World War British military
aircraft type that didn’t fly from here. Among the
numerous aircraft and weapons combinations
tested was the famous ‘Dam Busters’ Lancaster
with its bouncing bomb (which was itself tested by
the National Physical Laboratory, as described by
Fiona Auty in the Spring 2007 Communicator).
Several American aircraft, one-off prototypes
and captured enemy aircraft were also tested,
such as an ME109 that was captured by the
French and given to Boscombe for evaluation.
All this wartime activity, the need for massive
aircraft production with ever increasing new types
and rapidly advancing technology made evident the
shortage of suitable test pilots. They had traditionally
earned their ‘spurs’, through practical experience.
While they may well have been exceptional pilots, this
alone did not necessarily make them good test pilots.
By the end of 1942, the shortage had become critical.
From the London Gazette
15 November 1940
During an engagement with the enemy near Southampton on August 16,
1940, Flight Lieutenant Nicholson’s aircraft was hit by four cannon shells, two
of which wounded him whilst another set fire to the gravity tank. When about
to abandon his aircraft owing to flames in the cockpit, he sighted an enemy
fighter. This he attacked and shot down although as a result of staying in his
burning aircraft, he sustained serious burns to his hands, face, neck and legs.
Flight Lieutenant Nicholson has always displayed enthusiasm for air fighting
and this incident shows that he possesses courage and determination of a
high order by continuing to engage the enemy after he had been wounded
and his aircraft set on fire. He displayed exceptional gallantry and disregard
for the safety of his own life.
V Force in flight
A world first
The catalyst had been provided for the world’s first
Test Pilots School to be formed, here at Boscombe
Down in 1943. This was the beginning of a proud
tradition, with the first course of 18 students
finishing in February 1944. These were the first
pilots to have the honour to use the letters ‘TP’
after their names. It was at the start of the second
course that the prefix ‘Empire’ was added to the
name to recognise the fact that there would be many
students from overseas and the Commonwealth.
The first aircraft to join the school formally was a
Mk 1 Halifax. This was closely followed by a Master
III, a Hurricane I, and several others. In 1945, owing
to the rapid expansion of A&AEE and resultant
accommodation shortages, the Empire Test Pilots
School had to leave — only to return to Boscombe 23
years later in 1968, where it has remained ever since.
A&AEE tested aircraft to ensure their suitability
for their intended use by the services, as well as
conducting development and acceptance testing
on a range of equipment, some weird and some
wonderful, some useful and some useless. An
example of the latter was the ML Utility aircraft
with its inflatable wing made from balloon fabric,
tested at Boscombe in 1954 and affectionately
known as the flying Durex by all and sundry.
VAAC Harrier
ML Aviation’s utility aircraft
32 Aviation
TIARA and BAC 1-11 Unmanned Air Vehicle
V Force and beyond
English Electric Lightning
Modern environmental test facility
The development of the famous Avro Vulcan was
accelerated by the use of scaled-down versions
of the iconic delta-winged bomber. These were
designated as the 707, with variants A (high-speed),
B (low speed) and C (two-seat trainer). The first 707
took off from Boscombe for its maiden flight on
4 September 1949. The resultant Vulcan bomber
aircraft (type 698) took to the skies on 30 August
1952, followed by the first Vulcan B1 on 4 February
1955. The Vulcan joined the Vickers Valiant as part
of the UK’s renowned V bomber fleet, which was
also destined to include the Handley Page Victor.
Many varieties of aircraft were tested at
Boscombe during intense development of the
1940s and 50s, including the English Electric
Lightning. Moving into the 1960s, we arrive at
a most significant and controversial moment in
Britain’s, and Boscombe Down’s, aviation history.
Iconic, tragic TSR-2
The initial design for this aircraft was submitted
in mid-1959, with the contract awarded in October
1960 — a year late. In 1964, the first prototype was
transported in sections to Boscombe Down, where
it was reassembled over a period of three months.
XR219 made a relatively successful maiden flight on
27 September 1964. Its fourteenth flight, its return
to BAC Warton, was the first and only time that
the aircraft flew supersonic. A second prototype,
assembled at Boscombe, was destined never to fly.
The project was cancelled ‘with immediate
effect’ in the budget speech of 6 April 1965 by
the Labour government. Three aircraft went to
Shoeburyness for shooting and bombing practice, one
to RAF Henlow (ultimately to RAF Cosford’s aerospace
museum) and one to the Imperial War Museum at
Duxford. All remaining airframes were scrapped and,
bizarrely, all tooling, technical publications and parts
were destroyed. Even photographs were burned!
A famous quote from Sir Sydney Camm sums
up the TSR-2’s fate perfectly: ‘All modern aircraft
have four dimensions: span, length, height and
politics. TSR-2 simply got the first three right.’
33
The new millennium
TSR-2 seems a suitable place to break with the
last century and move into the present one. In
2001, the Ministry of Defence (MoD) split the
Defence and Evaluation Research Agency (DERA)
into two parts. It retained the smaller part,
renamed DSTL, and rebranded as QinetiQ the
larger part, including Boscombe Down. In 2002,
QinetiQ became a public-private partnership.
Boscombe Down’s focus is unchanged, with
its emphasis on development and evaluation
of aircraft and systems for use by the MoD.
Technology and equipment needs continue to
advance at an astonishing pace and, to compete on
the world stage both militarily and commercially,
we must at least keep up with, and preferably be
ahead of, the game. Two recent examples are:
The astonishing capability developed for the
Joint Strike Fighter in our Vectored-thrust
Aircraft Advanced Control (VAAC) Harrier,
which can, among other things, be landed
automatically on an aircraft carrier. It has also
recently been flown and landed by an ITN
journalist with no previous flying experience.
The technology that has recently been
demonstrated to enable QinetiQ's Tornado
Integrated Avionics Research Aircraft (TIARA),
flown by an RAF test pilot, to assume control
remotely of a BAC 1-11 aircraft as a surrogate
Unmanned Air Vehicle (UAV) along with a
further three simulated UAVs.
Our service personnel both need and deserve the
support that we have always tried to give them
through our many incarnations from A&AEE to
QinetiQ. Speaking as a former serviceman, it is
this that makes me proud to be a part of this
remarkable organisation at this very special place.
Boscombe Down has a considerable array of assets
and capabilities to carry it well into the future. It
has the longest and widest operational military
runway in the UK, its own design department and
a host of specialist facilities (such as an anechoic
chamber, an environmental test facility, a rolling
platform, and aircraft data recovery and analysis).
The list goes on but, most importantly, it has a
technical publications department!
Technical publications
Past
Under MoD ownership, the Support Authority
(SA) was responsible for Aircraft Publications
(APs). Special and experimental modifications
to aircraft were carried out in accordance with
design information and trials instructions, with
maintenance requirements documented on
a local form. While this was adequate then, a
more comprehensive solution became necessary
during the transition from the A&AEE to QinetiQ.
This led to the formation in 1998 of a Technical
Publications Department, with two technical
authors, two 386 computers, WordPerfect,
Microsoft Word and lots of outsourcing!
My predecessor began to develop the depart
QinetiQ Technical Publications Department
ment, upgrading computers, scanners and printers,
introducing PageMaker and FrameMaker, and
recruiting extra staff. Obsolete APs were adopted
and amendments were produced using various
methods, including scanning and conversion,
and reproduced to the style and specification of
the original. Modifications to fleet aircraft were
documented to the same style and specification as
the parent AP suite. Where necessary, illustrations
took the form of photographs, design drawings
and even authors’ efforts! With the purchase of
Alpha Jets came new requirements to translate
from German to English, validate technical content
and produce documents in Interleaf.
Present
The department employs 13 excellent authors,
who ensure that QinetiQ’s aircraft fleet has highquality technical publications that enable it to be
maintained and operated safely and efficiently.
For that, we cover the whole panoply of aircraft
documentation, ensuring that the many non-standard
and experimental modifications are correctly
documented. For our external customers, we provide
user, operation and maintenance manuals — and
anything else they require in formats they specify.
We use a range of authoring tools, including
FrameMaker 7.2 (unstructured), Interleaf (renamed
twice since we started using it) and Word. We use
various illustration tools, including Photoshop and
CorelDRAW, although we do not employ an illustrator.
Future
We are progressing towards the introduction of a
modern content management system and structured
authoring, which will allow us to concentrate on
our content and spend less time formatting and
template building. It is proving to be a challenging
exercise, considering the variety of specifications,
document types and platforms we cover.
We are a forward-looking department of a
forward-looking company, built on a tradition
and history of which we are justly proud. C
Ex RAF aircraft engineer,
Gene Sexton is Head of
Technical Publications at
QinetiQ, Boscombe Down.
A Technical Author for 11
years, he has been in his
current post for two years.
W: www.qinetiq.com
34 Methods
A framework for organisational structure
The Zachman Enterprise Architecture Framework provides a formal way
of defining an organisation’s structure, as explained by Warren Singer.
The Zachman Framework for Enterprise Archi
tecture and Information Systems Architecture was
created by John Zachman at IBM in the 1980s.
The framework borrows from business design
principles in architecture and manufacturing, and
provides a means of classifying an organisation’s
architecture. It draws on Zachman’s experience
of how change is managed in complex products
such as aircraft and buildings.
A framework for managing change
In today’s complex business environments,
many large organisations have great difficulty
responding to change. Part of this difficulty is due
to a lack of internal understanding of other areas
of the organisation, where legacy information
about the business is locked away in the minds
of specific employees or business units.
Figure 1. Adaptation of the Zachman Enterprise Architecture Framework
The framework provides a proactive business tool,
which can be used to model an organisation’s existing
functions, elements and processes, and to help manage
business change. It can also be used as a thinking
tool, to help organisations understand complex
issues and develop appropriate business strategies.
Widely adopted by systems analysts and database
designers, it can be used for information systems
architecture. However, John Zachman has stressed
that it extends to the entire enterprise architecture,
and is not restricted to information architecture.
The Zachman Enterprise Architecture Framework is
promoted by ZIFA (Zachman Institute for Framework
Advancement). Other enterprise frameworks have
been derived from it, such as the Federal Enterprise
Architecture Framework (FEAF), The Open Group
Architecture Framework (TOGAF) and the Department
of Defence Architecture Framework (DoDAF).
35
The framework has been employed in many
large organisations, including Volkswagen, General
Motors, Bank of America and Health Canada. It is
now in the public domain and can be used by any
organisation. If you want to purchase a poster-size
version or need further help, this can be found
on the ZIFA website at www.zifa.com.
The information in each row of the schema
provides a unique perspective of the enterprise.
Each cell in the schema must be aligned with the
cells immediately above and below it. All the cells in
each row must also be aligned with each other. Each
cell is unique. Combining the cells in one row forms a
complete description of the enterprise from that view.
Relevance to technical communicators
Schema columns
Technical communicators are closely involved in
information design and management, whether at
the level of a user, designer, integrator or developer.
Their role is associated with many different aspects
of an organisation. Business analysts are currently the
main providers of enterprise architecture services.
However, given the depth of business knowledge
and information management experience that many
technical communicators can offer, documenting
an enterprise’s architecture is potentially a service
that technical communicators with a good level of
business understanding could provide. In addition,
the way in which the Zachman model is structured,
in terms of a clear breakdown of information by
audience and by standard questions, will be familiar
to those working in the communication disciplines.
The columns represent the interrogatives or questions
that are asked of the enterprise. These are:
 What (data) — What is the business data or
business information?
 How (function) — How does the business
work? That is, what are its processes?
 Where (network) — Where are its operations?
 Who (people) — Who are the people that run
the business? What are the business units and
what is their hierarchy?
 When (time) — When are the business processes
performed? That is, what are the business schedules?
 Why (motivation) — Why are the processes, people
or locations important to the business? That is,
what are the business drivers or objectives?
The framework enables complex subjects to
be distilled into systematic categories, using
these six basic questions. The answers to the
questions will differ, depending on the audience
perspective (represented in the rows).
Using the Zachman framework
The framework is suitable for projects that require
understanding of the processes and technology
deployed in large, distributed organisations. It offers
a tool for managing a broad spectrum of enterprise
knowledge — often locked in the heads of key
experts — and is an effective way of capturing and
storing information about an enterprise’s processes,
procedures, systems, applications and people.
How it works
The framework is a classification schema,
represented visually as a table with columns and
rows (Figure 1). Each cell in the schema provides a
unique model or representation of the enterprise.
Schema rows
Each row represents a distinct view of the
organisation, from a unique audience perspective. A
row is allocated to each of the following audiences:
Planner understands the business scope and
can offer a contextual view of the enterprise.
Owner understands the business model and
can provide a conceptual view of the enterprise.
Builder develops the system model and can
provide a logical view of the enterprise.
Designer produces the technology model and
Online resources
Extending the RUP
[Rational Unified
Process] with the
Zachman Framework
http://tinyurl.com/2extru
What is the Zachman
Framework for Enterprise
Architecture?
http://tinyurl.com/33zv96
Zachman framework
(JPEG and PDF versions)
www.zifa.com/
framework.html
Zachman
Framework Applied
to Administrative
Computing Services
http://apps.adcom.uci.edu/
EnterpriseArch/Zachman/
Zachman Framework
Implementation
www.mega.com/index.asp/
l/en/wp/mega_zachman
Zachman Institute for
Framework Advancement
www.zifa.com
36 Methods
Figure 2. Example of the contents of cells in the Who column
can provide a physical view of the enterprise.
Integrator (sub-contractor) understands detailed
representations of specific items in the business,
although they will have an out-of-context view
of the enterprise.
User provides a view of the functioning
enterprise from the perspective of a user (for
example, an employee, partner or customer).
Rows are ordered in a quality assurance sequence.
Example of information in the WHO column
References
Loche, Stan (2003)
The Zachman Enterprise
Architecture, Metadata
Systems Software Inc.
Zachman, John (1987)
The Zachman Framework
for Enterprise Architecture.
Figure 2 shows sample content of the WHO column,
viewed from different audience perspectives.
Example of the first schema row: the planner’s view
This is the first row in the schema. The planner’s
view of the enterprise is contextual. The planner
looks at external requirements and business
drivers, and is concerned with representing the
business functions. The information of interest
to the planner is outlined in Figure 3.
Putting the framework into practice
A logical starting point is at the top left of the
schema, working your way down and across the
table. The relevant business information or ‘models’
used to represent a specific area of the business may
already exist in formalised business plans, project
schedules, system specifications, procedure guides,
organisation charts and other corporate documents.
Warren Singer MISTC is
a founding partner of
Cambridge Technical
Communicators, a
consultancy business
based in Cambridge,
UK. He has 15 years’
international experience as
a technical communicator.
E: warrens
@technicalcommunicators.com
W: www.technicalcommunicators.com
Figure 3. Planner’s view of the enterprise
As you go through the rows and columns of the
schema, you may find gaps where implicit information
known only to a single person or a few ‘experts’ must
be made explicit and available to a wider audience.
There may be instances of overlap or redundancy.
As a technical communicator, your role is to
ensure the information you gather is comprehensive,
reliable and appropriately categorised in the relevant
cell of the schema. At the same time, the business
objective in this exercise would be to gain a better
understanding of the organisation’s architecture,
with the goal of managing change and reducing
business redundancies and overlaps.
The information could be stored in a database
or other file management system that allows easy
retrieval. The categories of the schema will help the
enterprise not only to categorise information clearly,
but also to retrieve relevant information easily.
Templates and examples
You can view an adapted template of the framework
at www.technical-communicators.com/framework.
Examples of working implementations are available
on the ZIFA website (www.zifa.com). ZIFA also offers
training seminars and briefings, for those interested
in finding out more about the framework.
Recommending the framework for your organisation
The framework is a tool for creating knowledge and
clarifying thinking, and an aid to business analysis and
decision making. A strategic information asset, it can
help shape an organisation. Benefits of using it include:
Readily available documentation for the enterprise
Ability to unify and integrate business processes
and data across the enterprise
Increased business agility by lowering the
complexity barrier
Reduced solution delivery time and development
costs by maximising reuse of enterprise models
 Ability to create and maintain a common
vision of the future, shared by both the
business and IT communities. C
The 1st Integrated Dynamic Publishing Solution with Full DITA Support
D E L I V E R C O N T E N T C O N S I S T E N T L Y. Q U I C K L Y. P R E C I S E L Y.
by automating processes
Control content and processes to configure accurate publications:
• Create and author XML-based text modules
• Produce technical illustrations directly from
CAD models
• Compose documents dynamically
• Review and approve content using
workflow management
• Reduce translation time and costs
• Automate publishing of XML content
to multiple formats
• Promote reuse of content
Get the Most from DITA – with PTC’s Exper t ise and Competency
PTC is the first provider to fully and comprehensively support the DITA specification. With its
integrated, Web-based solutions, PTC provides a seamless integration between the product and
documentation development process.
For more information on increasing efficiencies and streamlining your document creation and
authoring using DITA & PTC’s Arbortext products, go to: www.PTC.com /go/dita
©2007 Parametric Technology Corporation (PTC). PTC, the PTC logo and Arbortext are trademarks or registered trademarks of PTC.
38 Methods
Successful migration of large data sets
Graham Every discusses the processes involved in high-volume data
conversion and offers guidance to ensure a successful outcome.
As with all projects, when it comes to migrating
large data sets into new systems or processes,
80% of the work is in the planning. It’s a
truism, but the more thought that goes into
the planning stages, the less chance there is
of large-scale problems coming to light late in
the process and the greater chance there is of a
successful conclusion and of client satisfaction.
The importance of planning can be most
clearly seen by splitting the conversion process
into seven separate stages, of which only one is
the conversion itself:
Identifying the client’s requirements
Analysing the data to be converted
Creating the specification
Creating the conversion program
Converting sample data
Converting the full date
 Overcoming real-world challenges.
I’ll discuss each of these stages in turn,
commenting on the processes involved and the
pitfalls to avoid in each case. I’ll conclude by
considering the issues of concern to the budgetholders — the timescales and the costs.
Choosing between industry-standard and bespoke DTDs
It is worth comparing the benefits of industry standards such as DITA or
DocBook with those of a bespoke application. In most cases, the industry
standard will need to be customised to meet the client’s requirements. In
practice, this often means that the client has to compromise an internal
process to fit the requirements of the application, or that the benefits of the
DTD are lost. A bespoke application need involve no such compromise, and
an experienced data conversion consultant will have a library of tried-andtested applications that they can use to make creation cost-effective.
In either case, the client will need to have access to a technical consultant
to monitor and maintain the DTD or schema once the conversion process is
in place. They may choose to have you migrate the maintenance skills to an
employee or to outsource to you when changes are required. Since neither
industry standard nor bespoke options are maintenance-free, the flexibility
of a bespoke DTD or schema is often the best solution. However, in the real
world, it is more than likely that the client will want the project to use the
industry standard, and this is often the deciding factor.
Identifying the client’s requirements
This is the stage where the project is scoped in
broad terms. What material is to be converted? Is
there an in-house DTD or schema that will need to
be followed? Is the data migrating to the web, to CD,
to print? These are the obvious questions, of course.
To increase the likelihood of client satisfaction
and a successful project, though, it is important
to find out about the client’s internal processes
and take these into account too. These might
range from the practical to the political. If
something ‘has always been done that way’
and it can be incorporated into the conversion
with no great difficulty, then do it. Successful
data conversion is something that fits into an
existing process, not something that requires
an existing process to be scrapped. If your
proposal requires the restructuring of an
internal process that has been in place since
the year dot, you will never get full buy-in — or
cooperation — from those involved in or affected
by the conversion. And that is a recipe for an
exhausting, painful and compromised project!
Analysing the data to be converted
This stage scopes the project in more detail. I
insist that the people who work with the data
on a daily basis are involved here because, quite
simply, they have more knowledge of the data
and the processes than the management team.
More than once, they have identified previously
unknown issues that have a massive effect on
the conversion process for projects on which I
have worked.
So, identify all sources of data and gather
samples of each of them. (Do double check this
list with the client. You would be surprised how
often something is forgotten and, clearly, the
later addition of a piece of legacy data adds time
and money to the conversion process.) Obtain
a copy of any existing DTD or schema too,
together with any associated notes.
Once you have all the data, analyse the
electronic versions. At paragraph level, check
for consistencies of styles and/or typography.
At in-line level, identify how special styles
are marked-up, whether that be through
character style or emphasis. (Ensure that your
identification is unambiguous: for example,
not all italicised text will necessarily refer to a
book title, so you will need to find additional
evidence.) While this stage is important, do
not try to get more than you can from the
documents: it may be that queries will need
to be put in place to be handled in postconversion clean-up. Once you have drawn your
conclusions, it goes without saying that they
need to be sense-checked with the client.
Once you and the client have analysed the
data, this is the point at which, if it is needed,
the DTD or schema is created or the suitability
of an existing DTD or schema is discussed.
Creating the specification
When writing the conversion specification, include:
Mapping between styles or typography and the
Elements in the DTD or schema
39
A detailed breakdown of what will be converted,
and, just as importantly, what will not be converted.
Once it is complete, as with all specifications,
agree it with the client and remember it is the
last chance you have to ensure you have set the
client’s expectations correctly.
Creating the conversion program
Once you have written or customised the DTD or
schema, it needs to be tested with a small set of
data. Once you are happy with the converted test
data, ensure it is what the client requires too. The
point at which the client sees the converted test
data is often the point at which you hear their
unspoken requirements for the first time. If the
conversion is to meet with the client’s complete
satisfaction, these unspoken requirements need
to be accommodated, even if they weren’t part
of the specification. In my opinion, if the data
conversion doesn’t meet the client’s precise
requirements, it hasn’t been successful and will
only serve to increase the suspicion in which
data conversion is held in some circles!
Converting sample data
Before beginning to convert all the data, I
strongly recommend converting a large sample
set. Doing this gives you — and the client — the
strongest possible reassurance that you have
picked up all the potential anomalies and that
the DTD caters for all eventualities before the
entire data set undergoes conversion. Naturally,
you need to adjust the conversion program in
the light of any findings.
Converting the full data
Once you are happy you have completed all the
preparation, you can convert the data, check it has
gone through successfully and complete any postconversion clean-up that is necessary. It is rare
that some manual intervention is not required,
but the work you put in before the conversion
should keep it to an absolute minimum.
Be aware, however, that it is often at the
clean-up stage that companies end up investing
absurd sums of money. This is largely due to
two scenarios. In many cases, it is because the
client has developed its in-house processes
but has not fed these developments
through so they can be included in the
conversion scripts. If not that, then it
is the effect of an unspoken or avoided
requirement that was not picked up
during the creation of the conversion
script.
is true that any data can be converted, GIGO
rules supreme: if you put garbage in, you will
get garbage out. The quality of the data to be
converted will have a direct correlation with the
quality of the conversion result, so it’s a matter
of degrees of acceptability. If the client knows
and, crucially, accepts that data conversion
is not a magical cure-all for the data’s
shortcomings, then all is well. Of course, this is
unlikely to be the case.
There are essentially two ways to improve the
quality of the end result, and you and the client
need to decide which method will be the most
cost- and time-effective. The first method is to
allot a period of time to post-conversion manual
clean-up. If it is a relatively small amount of
legacy data that is failing the quality control
tests, this is likely to be the solution. If the
problems present themselves on a larger scale
or if the conversion project is a rolling one, it
is likely that adjusting the source data is the
correct route. This might involve re-formatting
the text or, in extreme circumstances, it might
require an interim conversion.
When it comes to costs of this, and indeed
data conversion as a whole, it is, rather
unhelpfully, a case of ‘how long is a piece of
string?’ The only guidance I can give is that
cost is inversely proportional to the quality of
the incoming data. The more work involved in
preparing the data for conversion, the greater
the cost will be.
Conclusion
Converting large data sets can, and should, be a
fun and rewarding experience. Unveiling a
successfully completed conversion can draw
gasps of amazement at what has been achieved.
However, to get that gasp of amazement, you
need to have listened to the client at every stage
and adapted the conversion processes to fit
their processes wherever possible. You also need
to have set expectations so you have, in their
eyes, over-delivered. Automated data conversion
is often the solution for organisations looking to
maximise the value of their data but being a
realist, not a salesperson, is the best way to help
the client realise these benefits. C
Graham Every has
worked in the field
of automated data
conversion for over 17
years. His consultancy,
Graham Every Ltd,
provides large and small
volume automated XML
data conversion services
to businesses and
organisations worldwide.
He is also a well-respected
trainer and has spoken at
numerous conferences.
E: graham@
grahamevery.co.uk
W: www.grahamevery.
co.uk
Overcoming real-world challenges
The preceding may have given you the
impression that data conversion is a
relatively straightforward process and
that success is almost guaranteed as
long as you follow all the procedures.
Welcome to the real world! While it
40 Project evaluation
Documentation with a wiki: reception
Katja McLaughlin evaluates how users have reacted to the use
of a wiki for delivering internal best-practice guidelines.
In the Spring 2007 Communicator, I explained how
we at Sumerian use a wiki to deliver internal bestpractice guidelines and discussed some criteria for
selecting a wiki package. This article discusses how
the new delivery method was received by our staff,
and highlights some responses that you might
encounter when rolling out your own internal wikis.
Objectives
... a more uniform
and user-friendly
way of delivering
the guidelines than
disparate collections
of Word documents
or PDF files.
The objective of our wiki project was to deliver
documentation in a manner that would encourage
Sumerian analysts to make full use of the guidelines
and to help maintain them by contributing to their
content. We were prompted to consider new delivery
mechanisms because Word documents and PDF
files had proved cumbersome for such guidelines.
Also, many analysts were not keen to create their
own pages on the company intranet to share
hints and tips, due largely to the effort involved in
learning how to create and maintain such pages.
However, our wiki was not intended to act solely
as a delivery mechanism for the guidelines. Rather,
we anticipated that staff could use it to share other
information, too. We wanted the wiki to become a
dynamic place where everyone at Sumerian could
easily exchange information — using it to deliver
guidelines was to act as a catalyst for this.
Positive responses
Overall, the wiki has been a success, for Sumerian
wiki users in general as well as for technical authors.
General users
Sumerian staff have welcomed the wiki as a more
uniform and user-friendly way of delivering the
guidelines than disparate collections of Word
documents or PDF files. Moving from one set of
information to another is now seamless, provided
that the subject matters are conceptually closely
related. Our users have also liked the look and feel of
our chosen wiki package, which has probably contri
buted to their positive perception of this new tool.
The wiki has also got off to a good start in meeting
the objective of creating a place where everyone in
the company can easily create intranet pages and
share their own hints and tips. Soon after its launch,
the wiki became popular among a small group of
keen authors who were characterised by being quite
technical and by having a pre-existing need to share
large volumes of internal information. Typically,
these early users were carrying out solution
development or architecture work.
After a while, the guidelines and the other
content authored by the early adopters started to
attract more new users. As people started referring
others to information they had found on the wiki,
the number of registered wiki users and the overall
level of topic authoring started to rise. The result is
that the wiki is now also being used for increasing
amounts of non-technical information. For example,
recent content includes tips about sales techniques
and discussions about HR initiatives.
Our chosen wiki package automatically creates
home pages for new users as they register, and
we found that one way to help users make the
transition from wiki readers to wiki editors was
to encourage them to populate these home pages.
New users often do not have any immediate
changes they want to make to wiki text, which
means that they may delay learning about how
to edit pages. Creating a personal page solves
this problem by providing easy subject matter.
Trying out text formatting options in your
personal area also means that you do not have
to be embarrassed about initial mistakes.
Technical authors
From a technical author’s point of view, the
purpose of the wiki was not only to make the
guidelines easier to use; it was also important
that we encouraged staff to help maintain them.
Many wiki pages created by Sumerian staff have
slotted directly into the framework of ‘formal’
guidelines. While general users were unlikely
to write explicit guidelines that would replace
the need for a technical author to create those
instructions, they often wrote reference material
that was equally useful. Documenting detailed
technical reference information can be a lengthy
task for a technical author, so encouraging subjectmatter experts (SMEs) to create this material
themselves certainly saved time — which enabled us
to focus our technical writing resources on making
the high-level guidelines as easy to use as possible.
Even better news is the fact that many authors
took responsibility for maintaining content
that they created in the past. This means that
when technical authors create links to such
user-generated documentation, there is a good
chance that the material will remain up to date.
Mobilising SMEs to create reference information
is certainly worth considering for anyone contem
plating similar wiki documentation projects.
When it came to modifying existing pages rather
than creating new ones, it turned out that readers
were most likely to modify pages whose content
was not too formal. For example, guidelines for
running good customer meetings attracted more
additions than formal process descriptions. Even
though wikis enable users to edit pages as much as
they want, readers have exercised a fair degree of
self-restraint in modifying text that seems to have
41
already gone through a discussion and review cycle.
On the other hand, the fact that pages on our
wiki do not have clear owners has meant that
users do not seem excessively cautious about
stepping on other authors’ toes when modifying
content, which might otherwise keep them from
making any changes at all. As a result, the wiki has
enabled us to share information on equal terms,
and users do not appear to have been put off from
modifying content created by a technical author.
Overall, our experience seems to suggest that if
your goal is to use collaborative authoring as an
aid to technical authors in creating and maintaining
content, a crucial part of your wiki launch is to put
users at ease about editing pages. Explaining the
version control and alerting features of your chosen
wiki package is important, and seems to lower the
threshold for modifying existing information.
Another thing deserving of attention is the need
for text added to the wiki to be presented in a
reasonably consistent manner. On our wiki, users
have adopted a clear and easy-going style of writing,
suitable for internal documentation, without much
prompting. The text editor in our wiki package
restricts the formatting choices open to individual
authors; this has been a definite advantage in
ensuring that a varied group of authors can create
pages with a consistent look and feel, without
needing to refer to a formal style guide at every turn.
Challenges overcome
After getting people enthusiastic about reading and
then authoring wiki pages, we found we needed to
address confusion about when to use the wiki as
opposed to other means of storing and publishing
information. At Sumerian, we also have a corporate
intranet, a content management system for storing
documents and additional communication methods
such as team blogs. Consequently, it is a good idea
to clarify how users can select the most appropriate
publishing method for their information.
Another source of confusion was the non-linear
navigation structure of our chosen wiki package.
Some packages let you define an explicit tree-style
page hierarchy but, with most, pages live in a ‘cloud’
where relationships between topics are defined
solely by the links that authors add to topics.
A non-linear navigation structure can be both an
advantage and a disadvantage. Wikis with a bottomup navigation structure let you add topics without
having to consider which ‘area’ they belong to,
and the navigation structure evolves according to
readers’ needs as users modify pages to add links
to related pages or remove inappropriate links. If
someone needs to access unusual information to
which there are few links, they will still be able to
find it using the search mechanism. On the other
hand, one obvious disadvantage of a non-linear
navigation structure is that browsing topics can
be more difficult in the absence of a site map.
Because of these differences, it is important for
anyone planning to deploy a wiki to consider what
your preferred navigation structure would be and,
if necessary, have a plan in place to educate users
about it. For example, in addition to highlighting
the nature of the wiki navigation structure in
general, we found that Sumerian wiki users wanted
broad guidelines about how to find the right
balance between adding too many or too few links
to their pages, and whether to create long pages or
to split the content into several shorter pages.
As well as providing style and content guidelines,
it is worth ensuring that someone (for example, a
technical author or a separate information architect)
keeps an eye on how information is organised on the
wiki as a whole. After a good deal of new content has
been added, it would be helpful to check that wiki
users have been provided with enough alternative
navigation paths to the new information.
Challenges avoided
During our wiki launch, we also found that some
potential challenges that we had identified earlier
turned out to be not too problematic for our
wiki users after all. For example, in our chosen
wiki package, pages are created using a plain
text editor to add simple formatting mark-up to
the text. Given that our audience was generally
used to WYSIWYG editors, we anticipated that
this might cause some difficulties. However, even
fairly non-technical users do not appear to have
been deterred from adding their own content.
Though the functionality of the editor is basic,
it does pretty much everything we need it to do.
Part of the attraction of wiki authoring is this
simplicity: because technical authors are creating
content using simple tools, other staff can easily
participate in modifying that information.
We also anticipated that using a wiki to manage
a large documentation set might be problematic.
However, features to identify new, orphaned or deadend pages have meant that a technical author can
keep an eye on how users are organising information.
In addition, we considered whether the fact that
any member of the Sumerian staff can modify wiki
pages at any time might affect the authoritativeness
of the information. However, the version history
features on our wiki have ensured that readers can
always check who authored the content and when
it was last updated, enabling them to make a quick
assessment of the reliability of the information.
... readers can always
check who authored
the content and
when it was last
updated.
Conclusion
A wiki is not a silver bullet that will magically solve all
of your internal documentation problems, but our
experience suggests that it can be effective for
creating information that does not require strict
review and approval cycles. For us, the wiki has
proved to be a great tool for enabling Sumerian staff
to engage in collaborative authoring and share bestpractice information. For anyone contemplating
deploying a wiki for similar purposes, the key things
are to encourage users to move from being readers to
becoming editors of information, and provide them
with brief guidance and an informal framework
from which their own content can evolve. C
Katja McLaughlin
MA(Hons) MISTC
(née Mannerkorpi) is
a technical author at
Sumerian in Glasgow.
E: katja.mclaughlin
@sumerian.com
W: www.sumerian.com
42 Methods
Touching DITA: linking to other content
Ian Larner explains how you can control the creation of links from
a DITA topic to other DITA topics and also to external resources.
With topic-oriented writing, one aim is to
create self-contained topics that can be read
in isolation. In practice, authors usually write
several topics as a related collection. Readers
depend on links to move between topics and
retrieve information. For example, when working
with a task topic, readers need to refer to a
related concept topic or to complete another
prerequisite task topic. A collection of topics
might be presented as an online ‘web’, needing
appropriate links to guide readers between the
topics. A set of topics might be presented as a
PDF book, with different link considerations.
When designing and developing a set of topics,
you need to have a strategy for the links that
you want to create between topics, and to other
resources, and to understand the techniques that
DITA provides to control the creation of links.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "../dtd/map.dtd">
<map title="Driving">
<topicref navtitle="Driving the car" id="driving" href="tasks\tdriving.dita" type="task">
<topicref navtitle="Driving off" href="tasks\tdrivingoff.dita" type="task"></topicref>
<topicref navtitle="Accelerating" href="tasks\taccelerating.dita" type="task"></topicref>
<topicref navtitle="Changing gear" href="tasks\tgears.dita" type="task">
<topicref navtitle="Gears" href="concepts\cgears.dita" type="concept"></topicref>
</topicref>
<topicref navtitle="Slowing" href="tasks\tslowing.dita" type="task"></topicref>
</topicref>
</map>
Figure 1. DITA XML extract from driving.ditamap
Resources
DITA Cover Page:
http://xml.coverpages.
org/dita.html
DITA Focus Area:
http://dita.xml.org
DITA Open Toolkit:
http://sourceforge.net/
projects/dita-ot
DITA User Group:
http://groups.yahoo.
com/group/dita-users
‘Linking your content’ in
the DITA User’s Guide:
http://dita-ot.sourceforge.
net/doc/ot-userguide131/
xhtml/linking/linking.html
in this series. This includes driving.ditamap
shown in Figure 1. You can build the ditamaps
with the DITA Open Toolkit as described in
Communicator Winter 2006.
Free links from the topic hierarchy
The main part of a DITA map defines a hierarchy
of topics, like the navigation index for an online
web. For example:
Welcome to your car
- Driving the car [Task]
- - Driving off [Task]
- - Accelerating [Task]
- - Changing gear [Task]
- - - Gears [Concept]
- - Slowing [Task]
The topic hierarchy in a map provides some
automatic creation of links in output topics. When
you nest one topic reference (topicref) inside
another, this creates a parent-child pairing. In
Figure 1, the parent topic Driving the car contains a
collection of child topics starting with Driving off.
When you build a map, child links are added to
the parent topic output for each of its children.
Also, a parent link is added to each child topic
output for its parent. This all happens without
you needing to define anything. In Figure 2, you
can see the child links in the output parent topic,
Driving the car. You can also see a link to its
parent topic, Welcome, created from the topic
hierarchy in ditacars.ditamap.
You can control how a map generates links
from the topic hierarchy. One control is the
collection-type attribute of the parent topicref.
Links from DITA maps
Links for a sequential topic set
General guidelines for improving the retrievability
of information encourage authors to avoid
defining ‘inline’ links (within the body of a topic),
except where the reader must go off to another
topic at that point. Further, if you author an inline
link, you cannot reuse the authored topic without
considering the availability of the linked topic.
A better linking strategy provided by DITA
is to use DITA maps to apply links into topics
when building your web or other output. Defining
links within maps also enables you to change the
linking strategy without changing any topic files.
Just by creating a topic hierarchy, the map
adds some links into output topics ‘for free’.
You can also create relationship tables to add
links independent of the topic hierarchy. You
can refine the linking behaviour by changing
attributes of topic references in the map.
Descriptions and examples in this article are
based on the ditamaps used in previous articles
Suppose that a collection of child topics should
be read one after another in the order given in the
map. For this, you can define them as a sequential
collection by setting the parent’s collection-type
attribute to ‘sequential’. For example:
<topicref collection-type="sequential"
href="tasks\tdriving.dita">
…
When you build the map, the child links in the
parent topic are labelled numerically, as shown
on the right of Figure 2. Also, each output child
topic contains a link to the previous and next
topics in the sequence, as shown on the top left
of Figure 2. This all happens by changing only
the parent’s collection-type attribute.
Links for a family of topics
Suppose a reader of a child topic might want to
go directly to any of the other child topics. For
this, you can set the parent’s collection-type to
43
‘family’. This causes each child topic output to
contain related links to all other child topics in
the set, as shown on the bottom left of Figure 2.
Links from relationship tables
You can use a map to add links that are independent
of the topic hierarchy. Relationship tables can be
used to organise such ‘related’ links based on various
criteria. A common case is to organise relationships
by information type. In the table header row,
each column defines the default information
type and metadata for the column. For example:
In a row, each cell can contain one or more topic
references that are to be presented in output as
related links of the specified type. When you build
the map, each output topic in the row is given a link
to all other topics in other cells in the same row.
For example, in Figure 3, you can see a relationship
table with columns for task, concept and reference
topic types. Beside the table, you can see the links
in the output for the Accelerating task topic: a
Related concept link to the topic in the concept
cell, and a Related reference link to the topic in
the reference cell of the same row.
You can use the table, column and cell elements to
set default values for processing attributes such as
‘linking’, so you can control the linking behaviour.
Figure 2. Variety of links in HTML output from driving.ditamap
Control of linking behaviour
You can refine the linking behaviour by using
the linking attribute on topic references and on
relationship table rows and columns. The effect
of the linking attribute applies to the topicref,
row or column on which it is specified. That is,
if you have several topicrefs for the same topic,
you can specify different linking behaviour for
each of them.
If you want to output a topic that does not
contain some links to other topics, you can define
its topic reference with linking="targetonly". For
example, you might want to link lots of tasks to the
common Gears concept topic, but do not want the
concept output to contain links to all of the tasks:
<topicref href="concepts\cgears.dita"
linking="targetonly" …
Similarly, you can define a topicref with
linking="sourceonly". The output topic
contains links to other topics, but those others
do not link back to this topic. Ultimately, for no
links with the topic, you can set linking="none".
Links for required topics
For cases where one topic must be read
before others, you can set the topicref with
importance="required". This works for topics
in a sequence, family or table row. Consider
that the Accelerating task must be read before
the remaining tasks in the collection. If you set
<topicref importance="required" href="tasks\
accelerating.dita"> and then build the map,
the Changing gear task output contains an
Figure 3. Relationship table links in HTML output from ditacars.ditamap
additional Prerequisite link. For example:
Presentation of links
In a topic output as XHTML, the default transform
for a map adds links in several places (Figure 4).
Link sets are labelled; for example, links to related
concept topics are labelled Related concepts. The
exception is child links; to separate such links
from the content of the topic, you can use custom
XSL to override the ol-child-links and ul-childlinks templates of the dita2html.xsl transform.
Each link has a label. By default, the label is
the title of the target topic. It is good practice
also to give each link a description, which is
used to annotate child links and as mouse-over
text for other types of links. For example:
Figure 4. Link
positions
If the target is a DITA topic available to the build
process, you need specify only the href attribute
44 Methods
In this example, scope="external" indicates
that the target is outside the topic set for the
DITA maps being built. In Eclipse help output,
it causes the target to be displayed in a new
window or tab of the browser.
Inline links
When reading the body of a topic, if a reader
should go somewhere else, you can provide an
inline link. To do this, you add an <xref>, which
has attributes similar to a topicref in a map. At
its simplest, for an available DITA topic, you only
need specify the href attribute. For example:
<li><xref href="tadjustposition.dita">
</xref></li>
<li><xref format="pdf" href="prelimchecks.
pdf" scope="external">The Preliminary
Checks manual</xref></li>
The output is shown in Figure 5.
Links in PDFs
Figure 5. Extract from a PDF book containing both inline links and related links
If you have any
questions, or ideas for
future articles in this
series, please send
them to Ian Larner at
[email protected]
for a link: the build process can retrieve everything
else from the target topic. It can set the label as
the topic <title>, and the description as the topic
<shortdesc>. You can choose to specify a <linktext>
and <shortdesc> on the topicref to override what
would be retrieved from the target topic.
For a link to a DITA topic that is not available
when you build the map, set the topicref
attribute scope="peer", add <linktext> and
<shortdesc> elements within the topicref, and
set the type attribute. For example:
<topicref … scope="peer">
<topicmeta><linktext>Label for link.</
linktext>
<shortdesc>Description of link.</
shortdesc>
</topicmeta></topicref>
You can link to any target that is accessible
when the topic output is used, such as a web
page, PDF book or ZIP file. On such non-DITA
links, you should indicate the format of the
target; for example, format="pdf". You should
also add a <linktext> to label the link (if you
omit it, the href is used), add a <shortdesc> and
add a topic type if one applies. For example:
Ian Larner is an
Information Architect,
Software Engineer and
Author at IBM UK in Hursley
Park, Hampshire. He is a
UK DITA advocate, helping
IBM teams to adopt the
architecture and non-IBM
teams with its usage.
E: ian_larner@
uk.ibm.com
<topicref format="html" href="http://www.
istc.org.uk/Publications/communicator.htm"
scope="external">
<topicmeta><linktext>The ISTC
Communicator</linktext>
<shortdesc>The ISTC publishes a quarterly
journal, Communicator. This contains
feature articles and regular columns,
covering all aspects of technical
communication.</shortdesc>
</topicmeta></topicref>
When you transform a map to a PDF book, the
default behaviour of the DITA Open Toolkit is to
add inline links only. Parent-child and previousnext link relationships are represented by the
chapter, section, sub-section structure and page
flow of the book paradigm.
If you want to build related links in the PDF, you
can set the build property: <property name="args.
fo.output.rel.links" value="yes"/>
This causes the build to add a Related Links
section in each section when required (Figure 5).
Summary
For maximum reuse of topics, it is good practice
to avoid authoring inline links within topics
except where a reader must follow a link at a
specific point in the topic. Instead, DITA maps
provide flexible mechanisms to impose links
onto DITA topics when the map is built.
By default, links are added automatically
between parent and child topics, based on the
topic hierarchy in the map. The default links
can be changed by changing a few attributes, for
example, to indicate a sequential reading flow
through a collection of topics.
To add links from one topic to any other,
independent of the topic hierarchy, you can define
relationship tables. All topics in one cell in a table
row get links to all topics in other cells in that row.
You can refine linking behaviour, for example,
to indicate that a topic is linked to but does not
link back to other topics. Links can be to any
target that is accessible when the topic output is
used (such as a web page, PDF book or ZIP file).
The linking techniques described make basic
use of DITA. More sophisticated linking can be
implemented by overriding the default behaviour
of DITA transforms. For example, some of my
projects use keyref lookups to generate links
from a simple key when the map is built or
served. C
46 Tools
First steps in structure: rules
Steve Rickaby continues a beginner’s guide to structured working
in FrameMaker to cover further rule types supported in an EDD.
The previous article in this series
(Communicator Summer 2007) looked at how
editing works in structured documents, and
made a start on defining a simple EDD (element
definition document). This article goes into more
detail about rules in the EDD and how you can
use them to automate your writing environment.
Rules in the structure definition
As we saw in the last article, rules convey the
power of structured FrameMaker. The following
three rule types are essential:
 General rules. Every container element defini
tion must include a general rule, which specifies
the element’s permitted contents. The previous
article illustrated simple uses of general rules.
 Formatting rules. Any formatting control that is
accessible in FrameMaker can be included in an
EDD and referenced in an element definition.
 Context rules. These make an element behave
differently depending on its context within a
document’s element hierarchy. Context rules
Figure 1. A format change list to set indents
Figure 2. Referencing a format change list
can test the identity of ancestor elements,
the level of the element in the document
hierarchy, or its ordering.
Formatting rules
When designing an EDD, you have to decide
whether to control document formatting in the
EDD, in the document using paragraph and
character tags, or a combination of both.
Formatting rules enable you to use the
first and last of these options. However, it’s
important to note that in an EDD — in the
absence of other controls — formatting is
inherited by child elements from their parents.
This allows, for example, nested lists to be
formatted easily, by inheriting paragraph
formatting and adding only the required indent.
To define explicit formatting in the EDD, you
create a named format change list. A format
change list is a little like an element, but does
nothing by itself, and is referenced by other
elements. It can access any of the properties
specified by the Paragraph Designer. Figure 1
shows what a format change list looks like.
The figure also illustrates something unique
about format control in an EDD: in contrast
to paragraph tag definitions, format change
list specifications can be relative. The example
shows how you could increase the indent by
0.33 inch, or 2 pica.
Figure 2 shows how the format change list
defined in Figure 1 can be used in an element
definition. It also shows our first context rule, an
all-contexts rule. We’ll return to context rules later.
Using format change lists and inheritance enables
you to keep an EDD relatively simple. It is also
possible, however, for an EDD to apply paragraph
and character tags from the document. Figure
3 shows a simple example of this by expanding
on the definition of the Section element given in
the previous article. Here the paragraph tag Body
will be applied to a Section element’s contents
and that of its descendents unless overridden.
If, when an EDD is imported into a document,
any of the paragraph tags that it references
do not exist in the document, FrameMaker
creates default definitions for them. If this is
unexpected, it’s sometimes a hint that you’ve
misspelled a tag name in the EDD.
Context rules
Figure 3. Specifying a base paragraph format
Context rules could be said to be where the
fun starts with structured FrameMaker. They
are typically where the greatest complexity of
an EDD lies. Using a context rule, you can both
enforce and automate formatting in a document
47
Figure 4. A simple level context rule
Figure 5. A simple positional context rule
during writing and editing. Context rules enable
FrameMaker to test:
The level of an element in the document’s
element hierarchy
The position of an element relevant to its siblings:
first, last, only, middle, not first, not last and so on
The types of an element’s ancestors.
They also enable FrameMaker to apply
formatting to the relevant elements
automatically based on the above, using the
methods described in the previous section.
Context rules are checked and re-applied every
time the structure of a document is changed.
Figure 4 shows a level rule that applies the
relevant paragraph tag (Heading1, Heading2,
Heading3) to the contents of a Heading element
depending on the nesting level of its parent
Section element. Although simple, this rule
ensures that if sections are moved within a
document’s hierarchy — which you can do merely
by dragging them in the structure view — the
section headings are reformatted automatically.
Note that in all these examples the various
parts of element definitions are not entered by
hand, but are themselves predefined elements
built into FrameMaker itself and inserted using
the Element Catalog. We’ll see how this works in
the next section.
Figure 5 shows just one way in which you could
apply context rules to paragraph tags depending
on the ordering of an element. The two element
definitions specify Para and OrderedList, in which
each child element is of type Para, inserting the
first list element automatically. In the definition
of the Para element, a context rule first checks
to see if the element is a child of an OrderedList.
If so, it uses a nested subrule (1.1) to check
whether it is the first child of the list element.
If it is, FrameMaker applies the paragraph tag
NumericalList1 (which should reset the list
counter): if not, it applies the paragraph tag
NumericalList, which just increments it.
Context rules are particularly useful for
handling formatting issues such as this. Notice
how the two element definitions work together to
create the desired result. In the target document,
the writer inserts an OrderedList element from
the Element Catalog, then simply uses carriage
returns to add more list elements: FrameMaker
applies the paragraph formatting automatically.
As well as checking the immediate context
of an element, as shown in Figure 5, a rule can
also check the ancestors of the current element.
FrameMaker offers the notations shown in Table 1
Table 1. Context rule notations
Notation
Interpretation
ElementA < ElementB
ElementA is the parent, and ElementB is its parent.
ElementA < * < ElementB
ElementA is the parent, and one of its ancestors is ElementB.
ElementA < (ElementB | ElementC)
ElementA is the parent, and either ElementB or ElementC is its parent.
You can combine positional indicators with ancestor rules, too. For example:
{first} < ElementA
The current element is the first sibling of ElementA.
ElementA {after ElementB} < ElementC
ElementA is the parent, and immediately follows an ElementB whose parent is ElementC.
48 Tools
for this. The Structure Application Developer’s
Guide Online Manual, supplied with FrameMaker,
elaborates the entire syntax, with examples.
In reality, an EDD is likely to be far more
complex than the simple examples shown here.
However, they demonstrate the principles, and the
rules shown do work, despite their simplification.
Creating the EDD
So far we’ve talked about analysing document
structure and defining an EDD, but we’ve not
looked at how it’s actually done.
that FrameMaker has created by default. The
Element Catalog shows <TEXT>, indicating
that only text is allowed here.
2. Enter ‘Chapter’ and press Return. The Element
Catalog changes to show all the elements that are
now valid — these are the element type definitions.
3. In the Element Catalog, double-click on Container.
FrameMaker automatically inserts a GeneralRule
element and places the entry point in its text field.
Once again, the Element Catalog shows <TEXT>.
4. Enter the general rule, ‘Section*’ and press
Return.
5. Again the contents of the Element Catalog
changes to show valid elements. Doubleclick on ValidHighestLevel, and the Chapter
element definition is complete.
This demonstrates how a structure definition
guides and enforces valid document structure — in
this case the structure definition for EDDs that is
built into FrameMaker itself. Of course, the example
is a very simple element: in reality some iteration
is often required to complete element definitions.
Future articles
Figure 6. The contents of a new EDD, structure and document views
Figure 7. A Chapter element definition
You create a new EDD in FrameMaker by
selecting File>Structure Tools>New EDD. You
will notice when you do this that FrameMaker
has a whole host of structure-specific
commands collected under File>Structure Tools
and File>Utilities. The New EDD command
creates a blank EDD as a structured document
that contains only the declarations shown in
Figure 6, which shows both the structure and
document views.
The default declaration Automatically create
formats on import refers to FrameMaker’s
ability to create format definitions (paragraph,
character, table or cross-reference) when you
import an EDD that refers to such formats
into a document that does not already contain
them. If you do not want this to happen, you
can select the CreateFormats element and,
using the Element Catalog, change it to a
DoNotCreateFormats element. This is the better
option if you are creating formats manually.
FrameMaker has also created the first, blank,
element declaration. The process of defining
elements is guided by the choices presented in the
Element Catalog. To take a very simple example,
the sequence required to create the Chapter
element definition shown in Figure 7 is as follows:
1. Position the entry point in the Element field
The next article in this series will flesh out
the simple EDD examples shown so far with
other essentials such as text range (character
formatting), marker and cross-reference elements,
and look at testing EDDs. Further articles will
describe how to apply structure to unstructured
documents, and how to set up bidirectional
interchange between FrameMaker and XML.
For more information
For information on working with structured
documents and creating EDDs, Sarah
O’Keefe and Sheila Loring’s book Publishing
Fundamentals: FrameMaker 7 is recommended.
Scriptorium Press also offers a range of selftraining material that uses this book: the most
relevant here is probably Advanced Structured
FrameMaker: Building EDDs. www.scriptorium.
com/training/frame7train.html. There is also a
useful collection of white papers at www.adobe.
com/products/framemaker/indepth.html.
For wider information on structured docu
mentation, see A Gentle Introduction to SGML,
www.isgmlug.org/sgmlhelp/g-index.htm. C
Steve Rickaby BSc MISTC has been a freelance
technical author and editor for 16 years, and has used
FrameMaker for most of that time.
W: www.wordmongers.com
We work on
a team.
I like to use my
own HTML editor.
I need a RoboHelp®
alternative.
I need to convert
my WinHelp projects.
I’m using Microsoft
Windows Vista and
Microsoft Office 2007.
I write in
Microsoft Word.
We work on
a team.
I write reference
docs for my .NET
applications.
What are your documentation needs?
Today’s Help authors face a diverse set of requirements, but share one common goal—to deliver quality,
professional Help systems or printed documentation. Whether you’re a Help author, developer, technical
writer, part of a team or author independently, Doc-To-Help is the only tool that delivers a complete set of
technology that aligns with the diverse needs of today and the emerging needs of tomorrow (including
Microsoft Windows Vista, Microsoft Office 2007, and XML).
Doc-To-Help Technology Includes:
• Innovative Browser-based Output
• Word or PDF Manuals
• Word or HTML Authoring
• Powerful Conditional Content
• Use Any Editor
• RoboHelp, WinHelp, HTML Help Converters
• Team Authoring Support
• Content Variables (new in 2007 v2)
• Included Support and Maintenance
Just Released: Microsoft Sandcastle Plug-in
Doc-To-Help is the first and only documentation
tool to integrate with Microsoft Sandcastle.
Use the Microsoft Sandcastle Plug-In to:
• Create Reference Documentation in Minutes
• Use Microsoft’s technology for generating
reference material
• Compile reference material into any output
• Easily add narrative content to your
reference material
With a rich and broad feature set and perpetually evolving technology designed to accommodate every
writer’s needs, Doc-To-Help is truly the Help author’s companion.
LEARN MORE AND DOWNLOAD YOUR FREE TRIAL AT:
www.doc-to-help.co.uk/you
SALES: 0800 328 5271 • +44(0)1460 234636
©1987-2007 ComponentOne Europe Ltd. All rights reserved. All product and brand names are trademarks and/or registered trademarks of their respective holders.
50 Affiliate news
Consortium launches Internet research programme
The European Commission has
approved public funding of the THESEUS
research programme by the Federal
Ministry for Economics and Technology
(Bundesministerium für Wirtschaft und
Technologie — BMWi) in Germany. The
programme aims to develop a new infra
structure to enable us to make better
use of information on the Internet. Set
to run for five years, the programme
will receive some €90 million in public
funding from the BMWi. The portion
set aside for research and development
will be divided equally between science
and industry. A further €90 million will
come from participants in the industrial
and research sectors, so that a total of
around €180 million will be invested in
forward-looking research projects.
By the end of the year, 30 companies,
research establishments and universities
will have embarked on a variety of
exciting research products aimed at
developing user-oriented basic technology
applications and technical standards for
a new Internet-based knowledge-sharing
infrastructure. Consortium members
from industry will develop prototypes
of the new technologies and test them
in seven application scenarios. The tests
are intended to find short-term ways of
converting the technological advances
into innovative tools, commercially
viable services and potentially profitable
business models for the Internet.
The programme focuses closely on
forms of semantic technology that are
capable of recognising and classifying
the content and meaning of information
(words, pictures or sounds). With the
aid of this technology, smart computer
programs are able to understand and
replicate the context in which data is
used and processed. By applying rules
and classification principles, computers
can also draw logical conclusions from
content, and subsequently recognise
and construct links between various
items of information from diverse
sources. In future, Internet users will be
able to apply the standards and basic
technologies (‘semantic toolboxes’)
developed by THESEUS when they want
to create or process content, rules and
classification systems themselves, or
to process, collect and link content
from different media along ‘smart’
lines. In combination with semantic
methods of this kind, the Web 2.0 we
know today — with its principles of
transparent, open, interactive social
networking — will become the Internet
of tomorrow.
Some of the basic technologies being
developed are functions for the automatic
creation of metadata for audio, video, 3D
and picture files, and mechanisms for
the semantic processing of multimedia
documents and their associated services.
Research is also being done into new
machine-learning algorithms and dialogueprocessing systems that can assess a
situation and take the assessment into
consideration. Work is in progress on
innovative user interfaces, as well as on new
digital rights management (DRM) procedures
intended to provide better protection for
the holders of intellectual property and
marketing rights to multimedia content.
The THESEUS consortium is coordinated
by empolis GmbH, a subsidiary of arvato
AG and Business Affiliate of the ISTC. Its
members include Siemens, SAP, empolis,
Lycos Europe, Deutsche Nationalbibliothek,
the Deutsche Thomson oHG, intelligent
views, m2any, Moresophy, Ontoprise,
Festo, the German Mechanical Engineering
Federation (Verband Deutscher Maschinen
und Anlagenbau, VDMA) and the Institute
for Broadcasting Technology (IRT). The
consortium promotes close collaboration
between research and development
departments in industry and research
bodies in the public sector. The latter
include the DFKI (German Research
Centre for Artificial Intelligence), the
FZI (Research Center for Information
Technologies), Munich’s LMU (LudwigMaximilian-Universität) and TU (Technische
Universität), the TU Darmstadt, the
Technical University (TH) of Karlsruhe,
the TU Dresden and the University of
Erlangen. Nine member institutes of the
Fraunhofer-Gesellschaft are also involved.
For more information about the
THESEUS programme and the planned
application scenarios, visit www.
theseus-programm.de.
Challenges facing technical communicators
and drive competitive advantage. In this
paper, Innodata-Isogen proposes that
teams take a new approach. The approach
proposed in the paper ‘combines singlesource technologies, information reuse
standards, such as DITA, and innovative
sourcing strategies that include
offshoring and outsourcing certain tasks.’
For more information, download the
paper free (but registration required)
from www.innodata-isogen.com.
manager for the campaign, Arwyn Jones,
said, ‘Originally launched in October 2005,
the website has become an essential source
of information for those involved in the
waste industry. More than 500 registered
members, including waste producers
and waste regulators, have made it the
success it is — so much so that we needed
to redevelop the site to meet the needs of
business waste producers as they began
to see waste as a valuable resource.’
New features include an online forum
with specific threads for different business
interests, an advice centre with up-todate information and useful resources,
and a spotlight that highlights topics and
organisations of interest to business.
Funded by the Department for Environ
ment, Food and Rural Affairs’ Business
Resource Efficiency and Waste (BREW)
programme, the website is run by the Environ
ment Agency under its Waste Crime project.
Technical communication teams have to
keep pace with ever-tighter development
cycles and sophisticated tools, as well
as constantly evolving media formats.
Globalisation, localisation and translation
issues add to the pressure. The situation is
compounded by the need to control costs.
Meanwhile, many teams still battle against
top management’s perception that they
are not core to the business and simply
represent an added and unnecessary
cost. As a result, Innodata-Isogen says,
‘Technical writing is often a prime target
during corporate down-sizing activities,
leaving engineers, software designers
and project managers to struggle with
the documentation themselves.’
To help technical communication teams
meet these challenges, Innodata-Isogen
has published a white paper on how such
teams can simultaneously reduce costs
New website helps the environment
Businesses are being encouraged to
share hints, tips and best practices
for dealing with waste on a new and
improved website. The website, www.
wastematters.org.uk, covers issues such
as fly-tipping and waste reduction, with
expert advice from regulators such as the
Environment Agency on waste legislation.
Environment Agency programme
Industry news
CAA publishes new guide
As part of the preparation for the
introduction of non-precision Global
Positioning System (GPS) approaches
for general aviation in the UK, the Civil
Aviation Authority (CAA) has launched
a publication detailing how to fly the
approaches to airports and airfields.
The publication, CAP 773 Flying
RNAV (GNSS) Non Precision Approaches
in Private and General Aviation Aircraft,
is available on the CAA website at
www.caa.co.uk/publications and also
in printed form from The Stationery
Office (TSO). It includes:
 Requirements for pilot licensing and
minimum aircraft equipment
 How to set up the aircraft’s GPS
equipment to fly an approach
 A step-by-step guide to flying the
approaches, including pre-flight checks
 A guide for instructors
 A recommended training syllabus.
3di’s localisation business grows
3di reports strong growth in its
localisation business over recent
months, with increases in the number
of languages involved in projects, the
technical complexity of the requirements
and the number of industries involved. To
cope with this growth, 3di has appointed
Daljit Hanspal. Joining Rob Sexstone’s
localisation team in Ripley, Surrey, Daljit
will be working on customer projects in
the role of senior engineer.
He brings more than ten years’
experience as a localisation engineer,
gained with industry leaders including
SDL, Lionbridge and, most recently,
Thompson NETg (now part of Skillsoft).
During that time he has worked on
projects for Dell, Motorola, DerivCo
and Corel, carrying out detailed
analysis, troubleshooting and process
improvement consultancy.
Daljit’s range of expertise, and his
particular strength in the challenges
of e-learning localisation, will have an
immediate impact on projects.
Vista-compatible version of Weighman available
Avery Weigh-Tronix has released the
latest update to Weighman, its leading
weighbridge management software
application. The availability of release
7.08.02 brings Windows Vista compati
bility to Weighman’s customer base.
XyEnterprise releases Contenta DITA Version 1.4
XyEnterprise, developer of XML content
management and multi-channel delivery
solutions, has released Contenta DITA
1.4 — what it describes as the next generation
of DITA-based content management software.
The software’s new features extend DITA
Specialisation support to all out-of-thebox tools, enhance DITA Author Support
for the latest authoring tools, provide
collaborative review using XMetaL Reviewer,
support the latest version of the DITA
Open Toolkit, integrate seamlessly with
SDL’s Translation Management System,
and provide enhanced graphics support
for print and online delivery formats.
‘With the release of Contenta DITA 1.4,
we’re putting greater control in the hands of
the end user,’ says Debra Boczulak, Contenta
Product Manager, XyEnterprise. ‘Together,
Contenta and DITA can help companies
reduce the cost and learning curve of
implementing a component-based solution.’
For more information, visit www.
xyenterprise.com/products.
Compiled by Kathryn Valdal Fourie.
If you have a story for the news pages
contact us at [email protected]
Talking technical in any language
�
�
�
Improve your time to market
Reflect the quality of your products across all
languages
Reduce your localization costs
Faster
Better
Smarter
Lloyd International Translations provides language
and technology solutions that represent real value
for money
t: +44 (0)1829 730050
e: [email protected]
w: www.lloyd.co.uk
Technical Manuals
Marketing Material
Software
Translation provider since 1989
Online Help
Websites
Certified Investor in People
ISO 9001:2001
51
52 Editing
The right word: D to L
Jean Rollinson continues her exploration of the differences
between commonly confused words in the English language.
Defective/Deficient
Defective means faulty or not working
properly; deficient means lacking a
part or incomplete. This is another
pair of words where the distinction is
becoming blurred, but the difference is
there and should be borne in mind.
Discreet/Discrete
Like complement and compliment, part
of the confusion arises from the words
being pronounced in the same way
and derived from the same Latin root.
However, their meanings are different.
Discreet means prudent or careful
often in the sense of being able to keep
secrets or confidences; for example,
‘He made discreet enquiries into his
brother’s financial situation.’ Discrete
means separate, and is often used in
scientific writing to mean distinct or
individual; for example, ‘The compound
was composed of discrete particles.’
Farther/Further
The distinction between these two words
is gradually disappearing, but for the
moment there is still a distinction to be
made in some circumstances. Farther
usually involves actual distances; for
example, ‘Edinburgh is farther north
than York.’ Whereas further usually
involves figurative distance; for example,
‘I can take this plan no further.’
I/Me/Myself
Although usually not a problem in
technical writing, the increasing use
of myself in place of ‘I’ or ‘me’ in both
speech and writing is a trend that I find
very irritating. The words are different
and should be used in particular places.
I should be used for the subject of the
sentence; for example, ‘My mother and I
went to the shops.’ Me should be used for
the object of the sentence; for example,
‘Jo invited Pete and me to a party.’ Myself is
used for emphasis (‘I’d rather do it myself.’)
or as a reflexive pronoun (‘I was able to feed
myself when I was very young.’) Myself
is not a more formal word for me or I.
however, places where the implications are
different. For example, on an invitation:
‘Let me know if you will be coming’
means in the event that you are going
to come, tell me.
‘Let me know whether you will be
coming’ means let me know whatever
your decision.
Imply/Infer
Imply means to suggest; infer means to
deduce. In general, a speaker implies
and a listener infers.
Impractical/Impracticable/Unpractical
Impractical and unpractical have the
same meaning. If something is impractical
or unpractical then it can be done but is
not worth doing. However, if something
is impracticable then it cannot be done.
Intense/Intensive
Intense should be used to describe things
that are heavy or extreme or occur to a
high degree (intense sunlight). Intensive
should be used to describe something
where there is a concentrated focus
(intensive care). The difference can be
readily seen in the example given by
Fowler. An intense bombardment is a
severe one; an intensive bombardment
is one directed at a relatively small area.
Its/It’s
These really should not cause a problem, but
still do. It’s is the contraction of it is; its is the
possessive. If you are unsure, try using it is
and see if the sentence still makes sense.
Lay/Lie
These two words, in all their forms, are a
constant source of error. Unfortunately,
there are no simple rules; you simply
have to learn which is right. If in doubt,
use a different word. The following
sentences give the correct usages:
I lay the book on the table.
Last night, I laid my head on the pillow.
He told the dog to lie down.
The dog lay down and went to sleep.
I have lain in bed all day.
If/Whether
Less/Fewer
In most situations, these two are inter
changeable, or at least the meaning will
be clear whichever you choose. There are,
The general rule is that less applies to
quantity and fewer to number. Perhaps
a more helpful, although less precise
guide, is to use less with singular nouns
(‘less salt’) and fewer with plural nouns
(‘fewer people’). Constructions that need
consideration are those involving what
appear to be plural nouns, for example
distances or sums of money. In these
cases, the amount is considered as a
totality, meaning a single unit, so less
should be used. For example, ‘Some people
earn less than £8000 per year.’ and ‘I live
less than ten miles from my sister.’
Liable/Likely/Apt/Prone
These all indicate probability, but the
distinctions are worth noting. Apt is for
general probabilities, for example, ‘It
is apt to snow in January.’ Likely is for
more specific probabilities, for example,
‘It is likely to snow today.’ Liable
and prone are usually reserved for a
probability that arises as a regrettable
consequence. For example, ‘People who
smoke are prone to lung cancer.’ ‘People
who trespass are liable to prosecution.’
Licence/License
In UK usage licence is the noun and
license is the verb. So you hold a licence
to serve alcohol, but alcohol is served
on licensed premises. This is similar to
other pairings such as practice/practise
and advice/advise. In the US license is
used for both noun and verb. C
Jean Rollinson MISTC is a freelance technical
author, editor and proofreader. An associate of the
SfEP, she might be considered a lifelong pedant.
W: www.authoring-services.co.uk
Remember ORO when you need a
term defined or a concept explained.
Log in to the ISTC website at:
www.istc.org.uk
Click on Members Area and then on
Oxford Reference Online. Type in a search
term and Bob’s your uncle!
53
Book review
Professional Communication in Engineering
From the ‘Palgrave Studies in Professional and Organizational Discourse’ series.
By H E Sales, ISBN-10: 1-4039-4806-2, hardback, 254 pages, Palgrave Macmillan (December 2006), £50
Reviewed by Paul Newbold MISTC
This book is based on a six-year study
by its author of design and mechanical
engineers in the aerospace, defence
and automotive fields. It is not aimed
at technical communicators but rather
at engineers who have to write a lot in
their job and who could use guidelines
on how to write important documents
such as specifications and proposals.
One example it gives of the cost of
poor technical communication is that,
of the £20bn UK defence budget,
£2bn is ‘wastage’, much of which is
down to poorly written specifications,
requirements documents and contracts.
The introductory chapter outlines the
study parameters, including texts written
by engineers, 25 verbal interviews and
49 e-mail surveys. It also defines the
professional roles of engineers and outlines
why the subjects chose that career.
The rest of the book offers numerous
good and bad examples of the document
types, as well as case studies and
quotations from the study subjects.
For example, Section 7.3.1 describes all
elements of a proposal, from the covers
through to the appendices, illuminated with
samples from several actual proposals.
What are its bad points?
What does it contain?
Who might buy it?
The primary audience is engineers who
need to improve their writing skills in
general or who need to learn how to write
any of the document types covered by
the sections listed. I would recommend
it to engineering colleagues if I worked
in an environment where engineers
originate a lot of material and authors
have a role more focused on compiling
and editing. Technical communicators
will also benefit from the book if, for
the first time, they are joining a team
producing one of these document types.
The book may also be a useful addition
to academic libraries, as it enables students
to see how technically oriented business
communications work in practice.
This is not a book that you would read
from cover to cover. However, if you
were, for example, an engineer needing
detailed guidelines on how to write an
engineering proposal, Chapters 6–8
would be a good a start. C
The main sections are:
1. The Engineers
2. Engineering Practices and Procedures
3. The Engineering Product
4. Engineering Texts
5. Engineering Specifications and
Requirements
6. The Bid Process and Persuasion
7. The Presentation of Engineering
Proposals
8. Engineering Proposals: Discourse
and Information Structure
9. Executive Summaries [Writing]
It also contains a list of figures and
tables, five pages of references and a
nine-page index.
Well, with two grizzled generic ‘engineers’
poring over a composite image of
an engine block, a technical drawing
and a microscope, the cover is a little
dated in style (my wife thought it was
a 1970s textbook!). Skimming through
the pages gives a fleeting impression of
densely printed text with a handful of
monochrome images. The book would
benefit from the use of colour and better
layout. I suspect it has been produced
to a tight budget for a limited print run.
Conclusion
bout the book’s author
A
H E Sales is Senior Lecturer of English
Language and Linguistics at the College
of St Mark and St John, Plymouth, UK. She
teaches English Language and Linguistics,
including courses for engineers.
For more information about the book,
visit www.palgrave.com/products/
title.aspx?is=1403948062.
54 International standards
WG 2 meets in Moscow
Richard Hodgkinson, Convenor of Working Group 2
(Software and Systems Documentation), reports back from Russia.
Thanks...
Let me begin by thanking the
ISTC members who reviewed the
Final Committee Draft (FCD) of
ISO/IEC 26514 – Requirements for
designers and developers of user
documentation. Your comments
were well received and discussed
in Moscow. I’ll be sending you the
Working Group’s responses to all
of the comments shortly.
Russia and SC 7 plenary
Being interested in twentieth
century history, Russia was one
place I’ve always wanted to visit.
With many famous historical
buildings and monuments, it
was very interesting to observe
Graffiti – Moscow style
personally the transition between
the Communist and Capitalist
systems. Evidence of new wealth
new documentation standards was
was everywhere but many people,
progressed in the meeting:
especially the elderly, have been left
behind in the wake of these dramatic
ISO/IEC 26511 – Requirements for managers of
changes. Bureaucracy, queuing and
user documentation
paperwork remain part of daily life. We
The Working Draft of this standard was
also encountered very unseasonable
discussed and the editor will prepare
weather of 35°C, which led to some
a new draft for discussion at our next
very sticky moments that week!
meeting. Following that meeting, we
This was the annual plenary meeting
plan to submit the draft for public
of ISO/IEC JTC 1/SC 7 – Software and
Committee Draft (CD) ballot.
Systems Engineering, with over 130
delegates attending from around the
ISO/IEC 26512 – Requirements for acquirers and
world at the invitation of the Russian
suppliers of user documentation
Ministry of Foreign Affairs for Russian
The outline structure of this standard
Business. The meetings were held in
was discussed and the new editor will
the International Centre for Informatics
prepare a new draft for discussion
and Electronics. Fifteen SC 7 Working
at our next meeting. Following that
Groups were present, including WG 2.
meeting, we plan to submit the draft
for New Project (NP) ballot.
WG 2 – Software and Systems Documentation
The meetings took place on 20–25 May
(yes, we work on Sundays!) and in WG 2 we
had some old and new faces around the
table. The regular experts, Annette Reilly
(STC, USA), Ralph Robinson (STC, Canada),
Phil Cohen (ISTC and ASTC, Australia),
Professor Yoshikazu Yamamoto (IPSJ,
Japan), Tom Kurihara (Project Management
Institute, USA), Cerys Giddings (ISTC, UK)
and George Hayhoe (IEEE, USA) were joined
by Daryl Colquhoun (Australia).
ISO/IEC 26513 – Requirements for testers and
assessors of user documentation
New WG 2 documentation standards
The FCD ballot for this standard has
been successful, with over 140 technical
Work on our suite of replacement and
The NP ballot for this standard has
been successful. The Working Draft
was discussed and the editor will
prepare a new draft for discussion
at our next meeting. Following that
meeting, we plan to submit the draft
for public Committee Draft (CD) ballot.
ISO/IEC 26514 – Requirements for designers and
developers of user documentation
comments received and resolved
at the meeting. The editor has also
resolved the editorial comments
and has circulated a new draft
for WG expert comment, prior
to the Final Draft International
Standard (FDIS) ballot. This
ballot signifies that all of the
technical content is now consi
dered stable and, apart for new
editorial comments, the draft is
ready for approval or disapproval.
Together with the new draft, a
disposition of all national body
comments (technical, general
and editorial) has also been
prepared to accompany the final
ballot. Following FDIS approval
(hopefully!), the standard will be
published by ISO in late 2007 or
early 2008.
Next WG 2 meeting
WG 2 has been invited to meet before the
STC’s Regional Conference in Cleveland,
Ohio, USA in early October. As I’ve been
asked to present on documentation
standards at the conference, I’ll be
reporting on the event as well as the WG 2
meeting in the Winter 2007 Communicator.
WG 22 – Software and Systems Consolidated
Vocabulary
With the support of the IEEE Computer
Society, WG 22 has prepared a vocabu
lary of terms and definitions to enable
consistent use across all future SC 7
standards. The vocabulary is freely
available at http://comrie.computer.org/
sev_display/index.action.
Want to join in?
Please contact me if you would like to
participate, as contributor or reviewer,
in any of the WG 2 standards. C
Richard Hodgkinson FISTC has
participated in the development of
international standards since 1990 and
has been the editor of nine ISO standards
addressing icons, symbols, software
documentation and software accessibility.
He currently represents the UK on three
international committees.
55
Indexing
Search, or use the index?
Following the 50th Anniversary Conference of the Society of Indexers,
Bill Johncocks draws on his talk about changing user expectations of indexes.
A decade’s use of search engines has
blunted people’s determination to find
things out. They’re now satisfied with
almost anything about a subject, not
worried about balance or completeness,
and even happy to let a machine decide
for them what’s most important. The
idea that an index will reliably retrieve
everything significant, once taken on
trust, now evokes suspicion: how could
anything created using traditional skills
compete with computer searching of
the full original text?
More recently, the Web 2.0 phenomenon
has meant that users who were once
happy to consume Internet content now
want to create it. Web 2.0 encourages
the idea that, just as anyone can edit
(as on Wikipedia), so anyone can index
(as on Flickr). Collaborative tagging
assumes that adding more freely chosen
descriptors must automatically make
something progressively more accessible.
It would be odd if these trends didn’t
affect technical documents, as demand
for searchability leads to more manuals
being delivered on CD-ROM or over the
Internet. When that happens, the change
in format usually leads to a change in the
preferred access method because people
look for the search button on a PC screen
just as automatically as they turn to the
back of a book seeking an index. But do
they still find what they need?
Finding terms and finding subjects
Searching works less well because
indexes provide access to subjects, not
just words, and to their treatments,
not just their occurrences. Indexes also
provide links to related topics.
Even where language is well controlled
and a spade is never called a shovel, freetext searching misses out the crucial step
I stressed in my first article: thinking like
the user. Only an index caters for the
user determined to find shovels; only
an index can provide task-orientated
access to a product description. Online
help and product manuals most often
fail because they are inaccessible. You
can’t afford such failures, so introduce
lots of alternative entry points: modern
users expect more choice, not less.
Most users know the alphabet but
not all can spell. Put ‘batery’ into
Google and it lists over 400,000 hits
but suggests you might have meant
‘battery’ (144 million): an Acrobat
search will just return nothing. Look
in an index and you’ll find the correct
spelling in virtually the expected place.
Indexes also sort occurrences into
page ranges (which identify the fullest
coverage) and subentries separate them
into specific groups of manageable
size. Other methods don’t. Remember,
however, that we have no agreed
alphabetical order for symbols!
Finding occurrences and finding information
Full text search results are always
bloated by passing, duplicate and
negative mentions. I index from printed
proofs, then check and edit the draft
index against the PDF version. It used
to alarm me when, say, I’d put five page
locators against a topic, to find the
term occurred over a hundred times.
On ploughing through, I would soon
discover that these occurred on a much
smaller number of pages. Sometimes
there were ten in one paragraph and
often twenty on adjoining pages that
could be covered by a single page
range. Those I’d omitted added no
useful information, leaving me with
my original five intact and a forgivable
smugness. Remove the index and your
user is faced with the full hundred.
Of course, your few index entries
often provide much more: crossreferences or double posting unite in
one place the equivalent of several
hundred text occurrences. I’ve noticed
an increase in cross-references within
the text (for example, ‘for outdoor use,
See Section 6’) to compensate for the
likely absence of a good index.
As an aside, to avoid discrepancies
between the numbers shown on printed
pages and the page numbers shown in
Acrobat, avoid separate preliminary
numbering schemes. Indexing to
numbered sections, where they are
available, might also work. Generally,
a section concerns itself with an
identifiable — and indexable — topic,
while page boundaries are arbitrary. Like
hyperlinks, section numbers will take
users to a precise location, instead of
abandoning them at the top of a page.
Possible strategies
Try comparing search and index
performance on your own documents,
in Word or Acrobat. Traditionally, an
indexer has an advantage over his or
her readers, in that only he or she has a
searchable text. Check that your index
does the job as well. You’ll usually find
that it does it much better.
The conference came up with no
easy solutions to our book index
problems but we must work with our
natural allies — educators, authors,
publishers and, of course, technical
communicators — to rehabilitate proper,
user-friendly indexes. We also need to
re‑examine the assumptions underlying
our working methods. Internet users are
wrong about the superiority of freetext searching and so need educating,
but that doesn’t mean they’re wrong to
find some indexes user-unfriendly. We
can and should meet them half way.
Techniques developed when books were
the only instructional tools for indivi
duals may no longer apply. Many user
studies on student populations already
make uncomfortable reading for book
indexers. Are there any similar studies
for technical publications, I wonder?
A good index adds far more value than
online searchability. However, an index
that is little more than a permuted table
of contents, or that only extracts terms
from the text, obviously adds less. Many
manufacturers claim their users won’t
use indexes, but that’s usually just a
sign that their indexes are useless: they
need to put more, not fewer, resources
into indexing. We should remain open
to the possibilities offered by synonym
rings, tag clouds and topic maps but, at
present, a fully searchable document is
simply less accessible, and the product
it describes less usable, than one with a
well-designed index. Providing an index
should mean less customer frustration,
lower support costs and more repeat
sales. If only we could prove it! C
Bill Johncocks is a freelance Accredited
Indexer living on the Isle of Skye.
W: www.technicalindexing.com
Society of Indexers: www.indexers.org.uk
56 Translation
Making use of your audience analysis
A good translation starts with a good brief and, as our new Translation Editor
Romina Franceschina explains, a good brief focuses on the readers’ needs.
Not long ago, I received a call from
a client concerned about the quality
of a translation of some manuals we
had delivered. We arranged a visit to
discuss the situation and determine the
best corrective measures. We started
discussing the diverse industries that
buy the machines designed and built
by the client and, as will come as no
surprise to a technical communicator,
this proved to be key information.
On close examination of the
amended document returned by the
agent, it was clear that the translator
and editor had completely different
target audiences in mind. While the
translator had tried to be as technically
accurate as possible, the editor had
tried to make the text accessible to
a range of potential readers — from
an operator on an assembly line to
a technician in a laboratory. One
document, so many audiences!
This experience leads me to suggest
that two questions are relevant:
1. What makes a good translation?
2. What makes a good brief?
What makes a good translation?
From a functional point of view, the
translation process is designed to
ensure that the translated text meets
the needs of its intended readers. The
key words here are process and readers.
While the selection of an appropriate
translation process is the translator’s
responsibility, the process design itself
must take into account the intended
readership and use of the material.
The focus shifts from the translator’s
abilities to the readers’ expectations
and requirements.
Technical communicators will be
familiar with the idea of carrying out
audience analysis before creating
content. If that content will need to
be translated, the analysis should also
New technical communication newsletter
The Australian Society for Technical
Communications launched its first
electronic newsletter, ASTC e News,
this July. It is available on the ASTC
website at www.astcnsw.org.au.
address translation-related aspects
of the readers’ requirements. This
information will facilitate strategic
planning on how these expectations
can best be met. Within this paradigm,
quality is not a value that exists
outside translation but a standard that
is directly determined by the purpose
of the written word. Therefore, it seems
logical to infer that a good translation
is one that meets the needs and
expectations of its intended readers.
What makes a good brief?
With the intended readers and the use
of the translation in mind, a successful
commissioning brief will include
information and instructions to help
the translator develop an appropriate
strategy for the work at hand.
A text does not start with its first
capital letter and finish with the last
full stop. Its writer and its readers are
as much part of it as the grammatical
and stylistic elements. A good brief will
include information on the document’s
content, style and use. Commissioners
of translation services should be as
specific as possible and should not
exclude any information, regardless of
how obvious it may seem. Examples of
useful paratextual information about
the material are:
Who produced it
Who edited it
Who will use it
Whether it is ever printed
Whether it is protected by copyright.
Keep in mind that a good brief ensures
that everyone understands what needs
to be done and what result is expected.
It also gives linguists the opportunity
to raise queries and make suggestions,
or even to refuse work that is outside
their area of expertise.
When preparing a translation brief,
be sure to focus on your readers. This
checklist may come in handy:
1. Decide what material your readers
need. This will help you determine
not only what needs to be translated
but also which services you need: only
translation or localisation as well? If a
document is for information purposes
only, translation may be all you need.
If it is intended for publication, make
sure that proofreading and/or
editing are included.
2. Try to define who the target
audience is and where they are
based. This will help you determine
the language and style required for
the target text. Knowing where your
readers are located is essential to
selecting the appropriate language
variant. Knowing that your readers
are based in China is not enough:
you have to know whether they
need Mandarin or Cantonese,
traditional or simplified Chinese.
3. Think about how the intended readers
will use the material you provide:
♦ Will they have regular access to it?
♦ Will they have individual copies?
♦ Will they need to read it while doing
something else, such as following
instructions? The way that something will be read has a significant
impact on the way it is written.
4. If you know your readers and you
know their preferences, give guidance
on the desired and most effective style.
5. If your readers are used to specific
terminology or language use, it is
important to be consistent with
what they have had in the past. Try
to supply linguists with as much
reference material as is available.
This will also be useful for context.
Discuss the assignment thoroughly,
defining expectations and requirements
in full. The project manager and the
linguists handling the assignment will
have the knowledge, experience and
skills to help you visualise your
intended readers. Your reader-centred
decisions will have an impact on more
practical aspects of the assignment.
Knowing for whom you are translating
is crucial when deciding what linguistic
expertise is needed. C
Romina Franceschina MA MCIL is Director
of Translation and Quality at The ASK Group
Ltd. A former translator and university
lecturer with a postgraduate certificate in
translation skills, her main research area is
quality assurance and assessment.
W: www.translate.co.uk
58 Member profile
the implementation team responsible
for introducing SAP into the business.
What’s most rewarding about it?
Seeing a contract through from its
inception to successful delivery, having
played a major part in sorting out the
various problems along the way.
What’s hardest about it?
Explaining to customers why their expecta
tions have not been met, especially if it’s
due to poor performance on our part.
What have been the biggest changes
in the last five years?
In this issue, we talk
to Tony Eyre, who has
been one of our copy
editors for six years.
How long have you been a
technical communicator?
On and off, since 1987.
What’s best about it?
The feeling of achievement when a piece
of my work is used and appreciated.
What’s worst about it?
Not being appreciated as adding value
to a product or service — being seen as
a necessary evil that only adds to costs.
What’s your current job?
Project Engineer — not mainstream
technical communication but I do
still retain some connections with the
discipline. As a member of the business’s
project management team, I help set up,
manage and close down maintenance
and repair contracts for the submarines
business of Rolls-Royce Marine. I think
of my role as very much a facilitator
(or ‘greaser of wheels’). Working in a
customer-facing environment, I am
usually the first point of contact for
customer queries (and complaints). I
then liaise with people in the various
departments or teams within the business
to ensure that what needs to happen does
happen, so dealing with people in a fair
but firm way is an important skill.
I retain responsibility for the compe
tence and training of the company’s
pool of editors. I’m also a member of
Although I’m slightly out of touch, it’s
probably the continuing move towards
electronic publications, with the associated
need for mark-up languages such as
XML and tools such as FrameMaker.
How did you get into our business?
It was a second career and, in fact, I’m
now on my third.
On leaving school, I started my
working life as a trainee draughtsman
before moving into fabrication. That
kept me gainfully employed (with a
spell in New Zealand) until the mid1980s, when it became obvious that I
needed a change of career if I wanted to
stay in work through the leanest of the
Thatcher years. In 1986, a chance arose
to get myself re-trained as a technical
author under the government-run
Training Opportunities Scheme (TOPS),
so I grabbed it. I joined a Technical
Authorship course at Blackpool College
in 1987, which led to an authoring
job with a technical documentation
company in Derby, where I worked
mainly on rail-related handbooks.
My next move was to a job as an
employed technical author with a
manufacturer of heat exchangers.
However, this ended in redundancy in
1990 and led to a period as a contract
author, first at Nuclear Electric (now
known as British Energy) and then at RollsRoyce Marine in 1991. After six years as
a contractor in the technical publications
department, I had the opportunity to
join Rolls-Royce’s permanent staff. At
the time, the writing seemed to be on
the wall for contractors and so I took
the leap and became an employee. After
three more years, I was offered the
transfer into project management.
What qualifications do you have?
 4 GCE ‘O’ Levels
 ONC Mechanical Engineering
 HNC Mechanical Engineering
 BSc (OU) Science and Technology
I gained all but the GCEs later in life,
while working.
Is enough relevant training available?
Yes, there are plenty of training
providers around for most things
that a communicator would need to
know. However, I’m not sure that the
opportunity I had in the mid-1980s
to train for a new career and be paid
a subsistence wage while doing it still
exists today in what is, paradoxically, a
country run by a Labour government.
Have you found employers supportive
of your professional development?
In the case of my current employer,
Rolls-Royce, very supportive indeed. Both
opportunity and support are definitely
there for anyone who wants them.
Describe your worst work experience.
Being called to see a very irate customer
and having to listen to a tirade about
how disappointed he was in our
performance: worst was knowing that
he was correct, and that a good share of
the blame could be fairly placed on me.
Describe your worst job.
A short spell back on the shop floor at a
particularly backward fabrication company
while between ‘proper’ jobs. I was 47 at
the time and found the unaccustomed
physical effort, combined with the
poor pay and conditions, very difficult.
Luckily I was only there for five weeks
before I got back into an author’s job!
What are you reading at the moment?
A Year in the Merde — frivolous but
harmless fun, with the occasional poke
at the French.
Who is your favourite humorous writer?
PG Wodehouse.
Who most influenced your career?
Myself probably, but with unstinting
support from my wife.
What skill would you like to develop?
Playing guitar at least half way properly.
What else would you have liked to do?
Tree clearing — I tried this recently on
some very tall trees, chainsaw in hand
with buildings very close, and managed
to get all eight trees to fall more or less
where I intended (that is, not on the
buildings). Very satisfying. C
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

Cut away, explode or animate?

Transcription

Similar documents

ni.com - SDL.com

David Pogue`s missing manuals

Minding your language Setting procedures in stone

Communicator Summer 2010.indd

Power Pick Global Communicator Pro

Communicator Autumn 2014

Adopt-a-thon and Fundraiser Event

element ary school pupils` mag azine

London Bridge station map