communicator - istc.org.uk · communicator the institute of scientiﬁc and technical communicators...

CommunicatorThe Institute of Scientific and Technical Communicators

Spring 2006

S1000D-compliant illustrationsCreating and delivering standard graphic �les

Writing business operatingprocedures for a retailer

Upgrading toFrameMaker 7.2

Applying accessibilitypractice to localisation

Introducing structureto your authoring

Great Expectations?If you have high hopes for highstandards of translation, make the leapto ITR and discover why top qualityneedn’t cost you more!

Key features of our translationservices include:

• Translation of all types ofdocumentation from marketingcollateral to technical manuals

• Expertise with all major DTP toolsincluding single-sourcing for multipleoutput formats

• Localisation of software, online help,and corporate websites

• All major languages including Arabic,Chinese, Japanese, Korean andRussian

• Scaleable teams of domain specialistsready to meet the requirements ofany size of translation project

• Terminology management to achievetechnical accuracy and consistencyfrom project to project

• High-performance leveraging fromcustomised translation memories tohelp reduce your translation costs onan on-going basis

• Comprehensive linguistic qualityassurance processes designed tooptimise the success of yourtranslations in market

• Integration with your publishingenvironment and workflow processesfor painless file transfer.

1 Dolphin SquareEdensor Road

London W4 2ST

Tel: 020 8987 8000Fax: 020 8987 8008Web: www.itr.co.uk

Email: [email protected]

To find out more about how your company can enjoy all the benefits of

ITR’s services, please contact

ITR InternationalTranslation

Resources Ltd

Communicator Spring 2006

�Contents

Communicator The quarterly journal of the ISTC ISSN 0953-3699

The Institute of Scientific and Technical Communicators (ISTC)Carol Hewitt, ISTC AdministratorPO Box 522, Peterborough, PE2 5WXT: +44 (0) 1733 390141F: +44 (0) 1733 390126E: [email protected]: www.istc.org.uk

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.

11 Adopting structured authoringKay EthierExplaining the business issues surrounding this move

13 Can structure save the day?Gillis RudhDescribing the impact of structured authoring on one writer’s role

16 Pity the poor hirerColette ClenaghanLooking at CVs from the recruiter’s side of the desk

18 Fruit and vegetables: a winning entryPam NichollProfiling a project placed in the 2005 Documentation Awards

22 Finding common groundYvonne ClearyExploring the overlap between accessibility and internationalisation

24 Terminology management in focusEline BeunSuggesting how to manage terminology across the organisation

26 S1000D-compliant illustration filesDavid ManockCreating and delivering illustrations that comply with this standard

30 Programming: the wheel of fortuneAnthony SeatonPredicting the future of computer programming languages

33 LaTeX: an introductionMike UnwallaExplaining the history and capabilities of this typesetting system

34 Adobe FrameMaker 7.2: what’s the deal?Bernard Aschwanden and Kay EthierExploring the features of the newest version of this tool

37 Taking FrameMaker a little furtherSteve RickabyDemonstrating support for long documents with repetitious layouts

40 Affiliate and industry newsKathryn Valdal Fourie

44 IndexingBill Johncocks

45 EditingSociety for Editors and Proofreaders

46 Book reviewIain Wright

47 IllustrationBettina Giemsa

48 International standardsRichard Hodgkinson

49 TranslationMonica Basting

50 Member profileLinda Robins

cover Photograph courtesy of BAE Systems, showing Terrier combat vehicle with an engineer using a trilogi electronic technical manual

SubmissionsGuidelineswww.istc.org.uk/pages/journals.php

DeadlinesSpring copy by 31 January published 21 MarchSummer copy by 30 April published 21 JuneAutumn copy by 31 July published 21 SeptemberWinter copy by 31 October published 21 December

Back issueswww.istc.org.uk/pages/members/commun.php (ISTC members only)

Production teamEditorMarian Newell, [email protected] or 01344 626895

News editorKathryn Valdal Fourie, [email protected]

CopyeditorsTony Eyre and Nick Robson

ProofreadersTim Joynson and Linda Robins

LayoutNewell-Porter Limited, www.newellporter.co.uk

AdvertisingFelicity Davie, [email protected] or 01344 466600

SubscriptionsCarol Hewitt, [email protected] or 01733 390141


� ISTC news

Spring faceliftAs has become our custom, we have modified our visual design and house style so that we stay up to date. The most significant change is the introduction of a five-column grid for our feature articles. Each text column spans two grid columns, giving longer lines to facilitate reading. The fifth column is reserved for graphics, quotations, notes and credits. However, as this layout is less compact, we have retained a three-column grid for our news pages and one-page regulars. Many publications use a combination of grids, and we hope this solution will work well for readers who were finding the three-column grid too narrow for long expanses of text.

The other noticeable change is a move from Helvetica to Myriad Pro for our sans serif text in sub-headings and panels. Myriad Pro offers a wide range of weights and widths, enabling us to adjust the relative importance of elements on the page. In particular, the semi-condensed option, combined with wider columns in feature articles, means that sub-headings can be longer without running onto a second line.

I have been asked whether the colours of feature articles is significant. It is not. We introduced colour to make the journal more appealing and provide more distinction between successive articles. However, given the variety of content we carry and the varying proportions of articles on particular topics in each issue, using colours to denote content type proved impossible. Colours are chosen to tone with graphic elements if present and to provide an overall balance in each

issue. We have now introduced colour to the contents page, so you will know which colour each article uses.

Calls for contentDecember’s readership survey yielded good ideas for content. Please contact me if you can write about: A company’s products or activities,

and the technical communication work involved in them

Less familiar sectors, such as geology and meteorology

Research into the effectiveness of technical communication for its users

Linguistics.Note that one respondent asked me to suggest that writers refer to the Writers’ & Artists’ Yearbook for guidance on writing articles. There is a great deal of advice readily available on writing technique for different purposes. Communicator is an excellent showcase for contributors’ skills, but only if they work to the highest possible standard.

While on the subject of surveys, see page 10 for the results of our first ever Article of the Year competition. Congratulations to the winners.

Code of ConductThe ISTC’s Memorandum and Articles of Association have been the subject of a review over the past two years; the result will be presented at this year’s AGM. A similar review is required of the Code of Conduct and I have agreed to carry it out. If you would like to work with me on it, do get in touch.

In praise of holismOne of the three organisations from which the ISTC was created was the Presentation of Technical Information Group. This was founded in 1948 by Professor Reginald Kapp, the author of an early book on our field called The Presentation of Technical Information.

Professor Kapp’s son and daughter have created a website to make his more philosophical works available to a modern audience. If you are interested in the relative merits of materialism and holism, visit www.reginaldkapp.org. C

Marian Newell FISTC E: [email protected]

Education/training and attitudeIan KembleIn his ambiguous President’s notebook in Communicator, Winter 2005 (Is he really that pessimistic about the future of the profession?), Gavin Ireland is right to highlight two key aspects of profession-alism: education/training and attitude. It is generally agreed that technical communication in the UK has reached an historic watershed with the impending demise of the City & Guilds qualifications and the establishment of an Examinations Board by the ISTC to set examinations in technical communication from 2008.

In the university sector there exists, as Terry Searle comments in the same edition, a range of certificate, diploma and degrees courses, mainly at the postgraduate level. In addition, there is a good track record of collaboration between the educational and the professional sectors.

It is imperative that this cooperation continues and develops, if technical communication is to achieve the profess-ional status it rightly aspires to. Against a backcloth of limited resources, it is only through collaboration between the two sectors that can we look forward to establishing a robust education/training infrastructure. The future is bright, but only if we collectively grasp the opportunities that are coming our way.

Note from the Editor: See page 40 for more from ISTC Business Affiliates on education and training. There is news from the University of Portsmouth on its forthcoming MA in Technical Communication and from Cherryleaf on its new Technical Author Apprentice Programme (TAAP). As the difficulty of breaking into our field is well known, these developments are most welcome.

Naval-speakTony Eyre MISTCWith reference to page 49 of Communicator, Winter 2005, it might interest readers to know that, here at Rolls-Royce, we use a convention when writing submarine names that is agreed and preferred by the Navy. Single ships in commission (that is, in active service even if laid up for repair) are written in upper case: HMS TRAFALGAR. Ships of the same class are written with initial capitals but without ‘HMS’: Trafalgar Class (not HMS Trafalgar Class).

LettersEditorial


�Decommissioned ships are written with initial capitals but lose their HMS status: Valiant.

Testing candidatesBill Stevens MISTCTia Azulay’s article ‘Can your writers decode English?’ (pages 16–17 of Communicator, Winter 2005) correctly identifies the fact that interviewers must test the candidates’ skill set. Their CVs usually give you an idea of their capabilities, but where is the evidence? They may bring examples of their work, but is it their own work? To what extent was their involvement? As we now live in a culture where plagiarism and being ‘economical with the truth’ are acceptable, the onus is on the interviewer to separate the ‘wheat from the chaff’. This can only be done by thoroughly testing the candidates.

A few years ago, I applied for a job with a telecommunications company. They were looking for an experienced all-round author who would comple-ment and enhance the skills of their Technical Publications department. Part of the interview process included a series of tests consisting of: Writing a technical description of a

piece of equipment Critically reviewing the design of a

page and screen layout Highlighting the servicing aspects of

a circuit diagram Defining a list of acronyms pertinent

to the industry Highlighting differences between two

similar typed pages

Re-writing various sample texts A short test using DTP and on-line

documentation tools. The tests lasted three hours and I was offered the job, which I subsequently accepted.

Should the ISTC use tests when consi-dering applications for membership?

Gender-neutral writingLinda Robins MISTCRecently, participants in the ISTC Discussion Group have been corre-sponding on ‘gender-neutral’ writing. There could be scope for an article with guidelines for technical communicators. I’d welcome any authoritative source material from readers — links to books, articles or websites — even anecdotal evidence if it helps! Please reply to [email protected].

I’d like to think some broad guidelines on suitability could result. Thanks in anticipation.

Back issuesE Robert A Beck FISTCI have a reasonably complete collection of Communicator going back to the 1980s. If anyone would like them, I would be happy to pass them on, as long as the recipient covers transport costs from Vienna, Austria. If you are interested, please contact me on [email protected]

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.

We're talking your language

19/19a St. Andrews Road Bedford MK40 2LL

Tel: +44(0)1234 271555 Fax: +44(0)1234 271556

[email protected]

Using native speaking experts, our teams work with

technical authors in major corporations worldwide

to ensure that their customers get accurate and

effective messages in any discipline.

• Translation of manuals

• DTP in your Preferred Application

• Localisation of your Software

• Globalisation of your Website

• Translation of manuals

• DTP in your Preferred Application

• Localisation of your Software

• Globalisation of your Website

CORPORATE MEMBER ITI

Member

Association ofTranslationCompanies

CA T

X-Pubs 2006The first UK conference dedicated to XML publishing, X-Pubs 2006 represents a growing interest in the adoption of XML as a standard for organisational publishing. The event seeks to critique the established business justification for the adoption of both XML and DITA in organisational publishing.

By closely examining existing XML publishing implementations and drawing on the world’s most exper-ienced XML publishing consultants, X-Pubs hopes to expose the pitfalls and challenges that organisations wishing to adopt XML are likely to experience

X-Pubs will bring to the UK leading independent XML publishing experts, such as Ann Rockley, Dr JoAnn Hackos, Scott Abel, Kay Ethier, Rahel Bailie and experts from organisations such as Mark Logic, Mekon and Blast Radius.

XML publishing is often promoted as a panacea. The same justifications for its adoption keep recurring: content reuse, speed to market, increased accuracy, more relevant content, lower localisation costs and greater consumer satisfaction. Vendors position solutions as simple and painless, with some keen to promote XML publishing beyond technical publications and into marketing, training, customer service and engineering documentation.

But just what are the challenges facing us? What return have early adopters really enjoyed? What lessons can we learn? Is XML really being adopted outside technical publications? Find out at the London Gatwick Hilton on 20–21 June. For details, visit www.x-pubs.com.


� ISTC news

I want to talk about change this quarter. It’s said that change is the only constant, and that’s something that I try to remember when making important decisions about work, the ISTC and my personal life. It’s also said that variety is the spice of life, and that too can be applied to all aspects of life.

For those of you who don’t really know me, I served for ten years in the

British Army, I’ve played and helped coach rugby on and off for many years and, now in my mid-thirties, I’ve also positively avoided anything to do with dancing for my whole life. Why mention dancing? Well quite simply, a friend convinced me to go to dancing lessons once a week. Given my background, it took some convincing and I was certain that I’d hate it. However, I left there grinning from ear to ear and I’ve been doing it regularly for six weeks now. I’m completely hooked and loving every moment. Darren Gough and Colin Jackson from TV’s Strictly Come Dancing have a lot to answer for!

My ‘constant’ attitude towards dancing has changed and the variety has spiced up my life, making me an all around happier and fitter person.

I’m not suggesting that everyone should go out and learn to dance, although I think you’d be pleasantly surprised, but what I’m suggesting is that the same principles can be applied to the rest of our lives. For example, you could learn a new tool or skill at

work and vary your day-to-day jobs. I find that doing something different from time to time keeps my interest and enthusiasm up, not to mention improving my employability.

That’s work and play, but how about your profession? The ISTC has been changing a lot recently, and both Council and I think it’s for the better, but what do you think? After all, the changes we’re making are for your benefit, so please speak up if you don’t like them or if you have better ideas. I won’t pounce on you and get you to volunteer just because you have an idea or an opinion (although I will probably ask). We’re your elected representatives, but that doesn’t mean that we automati-cally know what you want or what you think. I’ll look forward to hearing your thoughts on changing the ISTC. C

Gavin Ireland FISTC E: [email protected]

Presidential address

2006 ISTC Conference - 3-5 October 2006First ever mid-week conference!

There is a better wayThe Britannia Europa Gatwick Hotel, Balcombe RoadMaidenbower, Crawley, West Sussex, RH10 7ZR

Member Rate £345+VAT

For further information, booking form and a full price list:

• E-mail: [email protected] • Telephone: Ann Little on 020 8422 4689

• Visit: www.istc.org.uk/pages/conference2006.php

10% early-bird discount*

*Book before 30 June 2006


7

Council is considering a proposal to establish a book-publishing arm to be called ISTC Books.

General descriptionThe ISTC would publish books in the field of technical communication. Initially, these would be short books of about 60 pages, on a single topic. ISTC Books would be run by a steering group of Council members. The actual work would be done by a commissioning editor and a copy editor. The books could be ordered from the ISTC website, and from online sellers such as Amazon. They could also be ordered through any bookshop.

Authors would be given a contract, broadly following the recommendations of the Society of Authors, and would be paid royalties.

Why ISTC Books?As a professional institute, the ISTC should be publishing its own books. It has published books before, as one-offs, but these have involved a great deal of work and expense. If the work were to be done by a paid commissioning editor and copy editor, and the books produced using print on demand, publishing books would be much more practical and profitable.

Council believes that there are not enough books on technical communication produced with a UK perspective and that we have members with the expertise and knowledge, as well as the writing skills, to produce useful and interesting books. The books would enhance the image of the ISTC, as well as reinforcing the professional standing of their authors.

Submission and decision processOnce ISTC Books is established, and the commissioning editor and copy editor have been appointed, authors would be required to submit to the commissioning editor a proposal in the following form, which is generally standard in the publishing industry: A two- to three-page general

description of the book A full list of chapters, with a

description of up to five lines of the content of each chapter

A sample chapter containing up to 5000 words

A statement explaining why the book would be of sufficient interest to technical communicators for some of them to buy it

A statement explaining why the author is a suitable person to write the book

A list of any competing books that have already been published.

The commissioning editor would review the proposal and then do one of the following: reject it, ask for changes or pass it on to the steering group, with a recommendation that it be accepted.

After acceptanceThe steering group would decide whether to accept or reject the proposal. On acceptance, the author would be sent a contract, together with a style guide and a technical specification for how the book was to be presented. As well as a paper copy, ISTC Books would need electronic copies in a prescribed format so that the book is ready to be sent to the print-on-demand supplier for production whenever an order is received.

Current status of ISTC BooksIn a letter in the Winter 2005 Communicator, I asked for preliminary ideas for books. At the time of writing, I have received one. The topic is of considerable interest and the author has a background that suggests he would be able to deliver a useful and marketable book. However, I had hoped for more than one proposal.

Consequently, I recommended that Council should proceed cautiously. At present, the proposal remains before Council. The first step would be to appoint the commissioning editor and copy editor, but Council will not do that until it believes that there are enough potential books to make the venture worthwhile.

This means that it’s important for me to hear from potential authors who believe they can write books that will be of value to people in our profession. If you have an idea, start by sending me a brief outline. I will then let you know whether I am ready to receive a full proposal. Once we have a better idea of the supply of manuscripts, Council can make a firm decision on the ISTC Books proposal. C

Alan Fisk FISTC E: [email protected]

ISTC Books: the next step

Call us: 01483 211533 www.3di-info.com High Street, Ripley,Woking, Surrey GU23 6AF

Seeking out the finestTechnical AuthorsWe have 10 years’ experiencein providing our clients withhighly-qualified andappropriately experiencedTechnical Authors, across theUK and Europe.

● Access to thousands ofhighly-skilled andexperienced candidates

● Contract or permanentstaff - who fit your culture

● Fully-managed projectteams

● Specialists in therecruitment of informationdevelopers – we don’trecruit for anything else

Remember ORO when you need a term defined or a concept explained. Log in

to the ISTC website at:

www.istc.org.ukClick on Members’ area and then on Oxford Reference Online. Type in a search term and Bob’s your uncle!


� ISTC news

This quarter saw the usual requests for help, with graphic formats and Word featuring heavily. Some of the discussions that evolved included which graphics format is imported best into a variety of document formats; how, why and when to use multiple sets of page numbering in a single document; and how to create a document that will print on both A4 and letter-sized paper.

ISTC becomes an examining bodyA question about where graduate trainee authors can be recruited from swiftly became a discussion about the ISTC’s new role as an examining body, as it takes over from City & Guilds in delivering the 5360 syllabus in technical communication. Concern was expressed that an ISTC qualification wouldn’t be as recognised as one from the C&G, but some people see this step as the perfect opportunity to raise the ISTC’s profile.

Expressing scientific unitsShould there be a space between a value and the descriptor of a scientific unit, and if so, what size should the space be? This prompted a debate on the use of non-breaking spaces, with reference to BS ISO 31, which gives guidance on units and their symbols but not on their presentation, and to BS ISO 1000, which does advise on the presentation. The debate also branched off into one about quality — should we strive for ‘best’, or settle for ‘good enough’?

Citing Internet referencesA member queried how references to information sources on the Internet should be included. The general consensus was that they should be included in the bibliography. According to a former student, Sheffield Hallam University’s MA in Technical Communication recommends using the Harvard system of Author, Date, Title, followed by ‘[on-line]’, and then giving the URL at which the reference is found.

Signature files on e-mailsAlthough not strictly a technical communication question, a debate

was raised on whether the initials of qualifications and professional memberships (such as MISTC) should be used in e-mail signature files and in other correspondence. Most answers thought it was appropriate to use ‘letters’ if they’re of relevance or of particular merit — for example, using MISTC on job applications.

Receiving reviews and editsOpinion was split in a discussion about the best way to receive reviews and edits — on a printed copy, by e-mail, using Word comments or the equivalent — and how to track changes made. Some preferred giving the reviewers a hard copy, others used an electronic document review form or held review meetings. The general feeling seemed to be that whatever method the reviewers preferred was probably best, however, in the interests of getting the review done.

Technical pubs and trainingA member solicited opinions on whether technical publications and technical training functions are more effective when in the same department, and commented that in her experience, they are. Several members felt that, while it is of benefit for publications and training to share a department and source material, the roles should be kept separate — a good author does not necessarily make a good trainer, nor vice versa.

Touch or press?A query was received about touch screen terminology — does a user ‘touch’ or ‘press’ a screen? The multi-purpose ‘select’ was suggested, but most replies preferred to use ‘touch’ for a screen and ‘press’ for a keyboard. ‘Tap’ was also suggested, as used for Windows Mobile. C

Catherine Sharp MISTC E: [email protected]

Discussion Grouphttp://finance.groups.yahoo.com/group/ISTC_Discussion

The InstituteThe Institute of Scientific and Technical Communicators is the UK’s leading body for people engaged in technical communication. It provides a forum for members to exchange views and represents the profession in dealings with other professional bodies and with the government.

The ISTC was formed in 1972 from the Presentation of Technical Information Group (est 1948), the Technical Publications Association (est 1953, later the Institution of Technical Authors and Illustrators) and the Institute of Technical Publicity and Publications (est 1963).

To join the ISTC or upgrade your membership, contact Carol Hewitt on 01733 390141 or at [email protected] or PO Box 522, Peterborough, PE2 5WX.

Council members

PresidentGavin Ireland [email protected] Fountain [email protected] Wright (existing site) [email protected] Butler (replacement site) [email protected] Newell [email protected] Young [email protected] Wood [email protected]

MarketingPaul Ballard [email protected] Fisk [email protected]

Other membersJulian Murfitt [email protected] Robins [email protected]

Company SecretaryCarol Hewitt

Newsletter EditorSophie Watson (layout and artwork) [email protected] Valdal Fourie (content)

[email protected]

International RepresentativeFlorence Dujardin [email protected]


�

After seven years of moderating the IASIG, Tony Kershaw has stepped down. Thank you Tony for all your help in those years, and welcome to Alison Peck, our new moderator.

Membership of the IASIGAnyone who is a member of the ISTC and who is an independent author or who has an interest in independent authoring can join the IASIG. Practising independent authors can have a listing on the Quality Authors website. A few members raised queries about eligibility, and Alison Peck (as moderator) wrote, ‘When does an “independent” author stop being independent? When they collaborate with someone else? When they employ someone? How would I know? And probably most importantly, do we care?’

The consensus was that an independent author is someone who is self-employed or an agency contractor. One person suggested that small independent authoring companies should also be included in the category, and one person suggested that partnerships should be included. Most people thought that the existing membership rules were satisfactory, and there were some interesting posts on why the IASIG should be open to people who are not independent authors.

Nick Brooker wrote that authors in full-time employment should not be excluded and that they might be able to help independent authors and illustrators to find short-term contracts and freelance work with their employers.

Gavin Ireland (posting in his personal capacity) said that he joined the IASIG when he found out he was being made redundant. Being a member of the IASIG before he became a freelance author was very useful and he would have been annoyed if he’d had to wait until his first contract before he could join.

Tony Kershaw wrote that ‘over the years, we’ve had several members drift from independent work to permanent work and back again… It’s worth having the “interested in independent work” criterion. It’s good that members can take the occasional permanent post, whilst keeping one foot in the independent world, without feeling they have to leave the IASIG.’

Looking for workA member asked about finding work and the state of the technical writing market. Dave Leonard gave a comprehensive reply. He thought that job hunting is still very difficult. The market is not good because a lot of manufacturing and software development has gone overseas for cheap labour, and technical writing work has gone with it. However bad a company’s current documentation is, they are living with it, and you have to convince them that they will be better off paying you to do it. He targets the people who have the job of writing the manual, because they often regard the work as an unpleasant chore. He didn’t find his latest two new clients — they found him, which means the active business of hunting for jobs isn’t looking promising. He suggested obtaining a listing on the Quality Authors website and setting up a company website, because an easy-to-find website might be the best way of generating new business.

Agencies, documentation houses, and other distributors of writing work tend to give jobs to the (reliable) people they have used before. So, take every opportunity: be seen to add value, show a ‘can do’ attitude, be helpful and accommodating, and do more than you said you were going to.

In a related topic, Marian Newell noted that www.itjobswatch.co.uk/skills_and_rates/technical%20author.do summarises the advertised rates for both permanent and freelance technical authors in the IT sector.

Promoting IASIGA few years ago, members raised funds to promote the QA website. Some money remains, and a long discussion ensued about how we might spend it.

Nick Brooker suggested that we properly promote the group’s collective expertise… and landed himself with the job. Alison Peck was also keen to promote the group and they’ve joined together in developing a promotional plan, which they presented to the IASIG and the ISTC Council. Alison has set up a ‘promotion group’ to get a balanced view of members’ opinions. C

Mike Unwalla FISTC E: [email protected]

Independent Authors SIGhttp://finance.groups.yahoo.com/group/ISTC_IASIG

New members

MemberSimon Alovisi StoneleighMaggie Bridgeman WadhurstTom Brindley Codicote Sue Buchanan LondonJames Hall ReadingDavid Hutchinson DesboroughJohn Martin CoventryJane Norton OxfordDaniel Osborne LeedsIan Stewart LondonKevin Watson Alexandria

AssociateGreg Bennett SurbitonLindsay Haddon NuneatonCiara MacMahon Dublin

StudentPeter Ward Wells

Transfers

FellowSimon Butler SwindonGavin Ireland NorfolkDavid Llewellyn SwindonDavid Longstaff Milton KeynesJames Moore SouthportSimon Rollitt AshbourneGeoff Rose FarehamRobin Smith FifeJane Teather LondonSophie Watson IpswichMary White Tetbury

MemberAmanda Bates ThatchamJames Bell BristolAnthony Cowling BuckleyBrian Gall AyrKen Goddard Rowlands CastleGraeme Horton DunfermlineHilary Mudge CalneGreg Stevens ReadingChristine Wieting Brighton

AssociateChris Gatland SouthseaGraeme Hendry CardiffJonathan Lane Bristol

RejoinersMarjory Bisset ReadingHugh Davies CheshamChristopher Godwin Dronfield WoodhouseGregor Grant SudburyStella-Marie Thomas TowcesterMichael Walsh Eastleigh

New Business Affiliates

Grade 1Ablewisp www.ablewisp.com

Member news


10 ISTC news

Thank you to everyone who voted for their favourite articles of 2005. Votes were spread across half the 42 eligible feature articles, confirming that there is demand for a wide range of content. I’m delighted to announce the results: Winner: Ian Larner for ‘Darwin

Information Typing Architecture’ Runner-up: David Farbey for ‘Are we

happy in our work?’Both articles appeared in the Summer 2005 Communicator.

When notified of his success, Ian said: ‘What a wonderful surprise! I am very, very honoured by the response. I would like to thank very much the readers on behalf of all the DITA team, who created such an interesting architecture to write about. I really hope that the article has helped readers of Communicator in their understanding of DITA — and perhaps encouraged them to get involved in the active community of DITA users and contributors.’

David’s response was equally enthusiastic: ‘I am delighted to learn that so many Communicator readers enjoyed my article, which was based on the dissertation I wrote for my MA degree. Clearly, research on the state of our profession is something that interests many people and I hope be involved in more research in the future.’

On behalf of all readers, I would like to thank Ian and David for creating

such interesting content for us. We will explore DITA more in the future and are always open to research-based articles.

The competition will run again at the end of this year, so look out for the form enclosed with the Winter 2006 issue and meanwhile start thinking which articles you find most interesting and useful. C

Marian Newell FISTC E: [email protected]

Article of the Year 2005

Stand out from the crowdwith an ISTC awardDo you design clear, concise and effective information? Of courseyou do! So why not submit an example of your best work for theISTC’s 2006 Documentation Awards?

It’s a chance to see how you measure up to your peers. Ifyou win, you will be presented with your award in front ofan audience of technical communicators and publicationmanagers at the ISTC Conference. Your name, and yourcompany’s name, will be publicised in the ISTC’s journal,Communicator, as well as in the newsletter and in pressreleases to the media at large.

In a competitive world, winning an award could put you at the head of the queue for future contracts or jobs.

• Entries must be written in English.• Entries must have been issued between April 2005 and July 2006.• ISTC membership is not required.• Winners will be notified in September 2006.• Awards will be presented at the ISTC Conference in October 2006.• Closing date for entries is 1 August 2006.

For more information, visitwww.istc.org.uk/pages/awards.phpor e-mail [email protected]

CLASS 1 PRINTED DELIVERY

Class 1a Technical Information(sponsored by AST

Author Services Technical)

Class 1b Non-technical Information

(sponsor invited)

CLASS 2 ONLINE DELIVERY

Class 2a Technical Information(sponsored by AST

Author Services Technical)

Class 2b Non-technical Information

(sponsored by Plain Words)

Ian Larner David Farbey


11

Moving to structured authoringKay Ethier explains some of the business issues that surround a move to this method of publishing.

Methods

This article describes some of the actions and costs involved in a structured authoring implementation. It outlines the benefits of implementing structure, and the advantages and disadvantages of moving to structured authoring. This article also examines the process of implementation, its impact and the related decisions you’ll need to make.

Why move to structured authoring?Structure is not needed in everyone’s life. Structured authoring is not a necessity, and in fact some companies do not gain significant benefit. Taken further, determining the best structure for your content is no simple decision, so choose wisely.

While working in a structured authoring environment often proves beneficial, it is critical to analyse content needs before making this move. Doing so enables us to ensure that our efforts will be worth the investment. Otherwise we — and the organisations for which we work — will expend considerable time and effort in implementing a structured document publishing process with dubious results.

Ten years ago, few foresaw the paradigm shift from desktop publishing to web-based publishing. Since that time, the widespread adoption of web-based technologies has forever changed the way we create, maintain, access, archive and deliver content. Against such a backdrop, we suggest that few can predict what publishing trends will occur in the coming decade.

With that said, there is considerable momentum in the business world to find new ways to manage the content we create. Traditional publishing technologies often fail to provide the return on investment that structured authoring can provide. Structure enables us to do more with our information: it comes at a price but there are often great benefits to structure that make the extra investment worthwhile.

The question of whether to move to a structured authoring environment requires careful consideration. Decision-makers must consider, among other things:What issues are currently being faced?Is incorrect information being distributed?Are customers unsatisfied?Does it take too long to make changes to

important information?Is the authoring process complicated by

formatting and layout tasks?Are there regulatory compliance issues that

should be considered?Is moving to a structured authoring environ-

ment more a matter of style than substance?

How to move to structureIf you decide to use a structured authoring environ-ment, adopting a workable structure involves:1. Analysing your content and processes2. Evaluating existing structures to determine if

one might be a fit for your content3. Implementing your structure, including both

tools and author training4. Authoring in your structure, possibly

starting by training your team so that they understand the template.

Refer to the resources at the left for sources of potentially useful information.

Impact of authoring in structureMoving to structured authoring may have an impact on workflow, workforce and the roles and responsibilities of your documentation team members. This section examines implementation-related changes and costs.

Determining costsMany organisations believe they don’t need to switch to a structured authoring environment because they are able to author, maintain and publish documents in multiple formats successfully in an unstructured environment. These same organisations often do not know how much money it costs to support their unstructured authoring efforts — nor how much money, time, and effort they could save by adopting a structured approach — and they therefore lack a financial incentive to change.

Add to the mix the fact that calculating an accurate return on investment may be difficult. An experienced consultant should be employed to assist in calculating return on investment, as well as both the hard and soft costs of moving to a structured authoring environment.

Software and personnel costsStructured authoring tools vary in price from under a hundred pounds to several thousand pounds for each user. The costs for personnel, training and overheads are significantly higher than the cost of acquiring software tools.

Writing structured documentation requires experience and skill sets that most authors lack. Two types of personnel are needed: document designers and subject-matter authors. Other roles may also be needed, depending on the size of the project and difficulty of the implementation.

Document designers are technical personnel who design and manage DTDs (Document Type Definitions) and produce templates for structured authoring. Those selected to fill this role are likely

Resources

http:// groups.yahoo.com/group/xml-users General XML group that often discusses structured authoring.

http://xml.coverpages.org XML articles for beginners as well as advanced users.

www.hyperwrite.com/features/semantic_structured.htm Article that explains structured authoring.

www.travelthepath.com/structure.html Bright Path Solutions’ structured authoring area.

Do you reuse?

The way we create and publish content is evolving; XML and the Darwin Information

Typing Architecture (DITA) are making reuse of content a reality for many organisations.

Some organisations’ publishing systems are evolving into enterprise wide single-sources

of content which connect technical documentation, customer service, marketing,

engineering and training content into an effi cient multi-channel publishing system.

But how easy is it to achieve the XML promise? X-Pubs seeks to investigate what challenges

early adopters of XML publishing technology have faced, how we can learn from these

early pioneers and what ROI is really being enjoyed.

Europe’s Largest XML Publishing Conference20- 21st June 2006

With Keynote Speakers

» Ann Rockley Author of Managing Enterprise Content and President of The Rockley Group

» Dr JoAnn Hackos Author of Managing Your Documentation Projects and member of OASIS DITA Technical Committee

Join us at X-Pubs 2006. Just visit www.x-pubs.com or call 020 8722 8400 to book your place.

The London Gatwick Hilton, 20-21st June 2006

Gold sponsers

www.x-pubs.com


Can structure save the day?After 35 years without structure, Gillis Rudh describes his first encounter with XML.

1�to command higher salaries than subject-matter authors. DTDs may be written in SGML (Standard Generalised Markup Language) or XML (eXtensible Markup Language). With few XML experts available, salaries for authors with XML and structured authoring experience are much higher than those without such experience, making it worthwhile experience to gain. XML authoring tools include Adobe FrameMaker, PTC Arbortext Editor and BlastRadius XMetaL. Some companies also use open-source tools or custom-built systems based on online forms. The latter enables authors to enter their content into fields that are then saved with XML tags automatically inserted.

Training costsStructured authoring involves training. Some software manufacturers estimate it will take untrained authors three to six months just to learn the basics whereas, with proper training, authors can begin using the new authoring environment effectively right away. Training costs vary, depending on the tools and technologies selected, but are usually hundreds of pounds for each student-day. While training increases up-front costs, it also significantly increases the return on investment by reducing both learning curves and change management issues.

Benefits often outweigh costsThe benefits of structure often outweigh the costs. Common benefits include:Faster time to market Shorter content life cycle Less focus on format and layout More focus on content creation Faster reviews and approvals Lower content maintenance costs

Improved use of limited resources Repetitive processes eliminated More time to add value to content Fewer resources required to create new

information products

Having worked in technical writing for over 35 years and for a variety of customers, I have taken on many different publishing roles. However, in all those years, I had never been closely involved in the SGML world (or, at least, not for long periods). I had only listened to old colleagues who were all very sceptical about the ‘structured world’. One said, ‘It is too complex and you can no longer write what you need’. Another said, ‘You will never be able to have an overview anymore’.

After these not-very-reassuring judgements, it was my turn to step right into the XML world.

More time for innovationIncreased accuracy and consistency Reusable content updated in one place Errors fixed quickly Content updated automatically Increased quality through reuse Increased control of product and company

brandingIncreased productivity Less time spent formatting content More time spent authoring better content Multi-channel publishing and single

sourcing Reusable elements reconfigured into new

information productsReduced translation expense Better control over content to be translated Reusable elements are only translated once Less retranslation of unchanged content

Improved revision management Better revision control and change

management Regulatory compliance issues addressed

through audit trailEnhanced information retrieval Easy to locate, retrieve and reuse content More ways to search for and locate targeted

informationAbility to share information easily with others Enhanced interoperability Less time spent converting content to

formats others can use Less reliance on proprietary software code

and formats.

SummaryStructured authoring provides benefits to authors through ease of formatting and to companies through the provision of content as data. The latter can allow future expansion beyond the mere publication of information. Once you are up and running, you can extend your structure to meet future needs. C

Was it scary? No, I am not that kind of person. I saw it more as a challenge.

The traditional wayI started my writing career long before personal computers became working tools. Back in the ‘Stone Age’ (early 1970s), handwriting was our only tool. For reasons I still don’t know, typewriters were not available in my office (too expensive, perhaps). Nevertheless, I managed to write many technical documents during my first five years as a technical writer. At that time, I was employed by SAAB (Sweden’s only military aircraft manufacturer).

Kay Ethier is an Adobe Certified Expert and Adobe Certified Instructor in FrameMaker. She is also a WebWorks University certified trainer. She helps clients to create a variety of documents, including online help, training materials, user guides and maintenance manuals. E: kethier @travelthepath.com W: www.travelthepath.com

Do you reuse?

The way we create and publish content is evolving; XML and the Darwin Information

Typing Architecture (DITA) are making reuse of content a reality for many organisations.

Some organisations’ publishing systems are evolving into enterprise wide single-sources

of content which connect technical documentation, customer service, marketing,

engineering and training content into an effi cient multi-channel publishing system.

But how easy is it to achieve the XML promise? X-Pubs seeks to investigate what challenges

early adopters of XML publishing technology have faced, how we can learn from these

early pioneers and what ROI is really being enjoyed.

Europe’s Largest XML Publishing Conference20- 21st June 2006

With Keynote Speakers

» Ann Rockley Author of Managing Enterprise Content and President of The Rockley Group

» Dr JoAnn Hackos Author of Managing Your Documentation Projects and member of OASIS DITA Technical Committee

Join us at X-Pubs 2006. Just visit www.x-pubs.com or call 020 8722 8400 to book your place.

The London Gatwick Hilton, 20-21st June 2006

Gold sponsers

www.x-pubs.com


1� Methods

might say that the preview in Epic is not the best but, after a few weeks or months, you get used to it. And, if you have a good publishing tool, it is acceptable to check the layout later on. The idea with structured documentation is, of course, that the appearance of the information can change from one medium to another. The writer does not have to manage the layout — one thing less to worry about.

TopicsThe pieces of information that I was working with were not very small. They were also well balanced in size and complexity. We call these pieces ‘topics’ and that is just what they are. One such topic contains all you want to tell related to a certain heading.

The topic-based structure gives you all the support you need to focus on what you want to tell the reader. Moreover, if one topic is not enough, you can use more topics to tell the whole story. It is not as restrictive as my former colleagues told me.

IllustrationsAs I was used to working with illustrations created mainly in Adobe Illustrator, I was unhappy to have to convert nice vector graphics into ugly TIFF files. That is not a requirement of XML, though; our system was just made that way and I simply don’t like it.

DatabaseBoth illustrations and topics then have to be checked into a database. InfoShare from TriSoft was used on this project. It enables you to add metadata that can later be used to identify certain topics for reuse.

So, what is the problem?Now that I am back working with unstructured FrameMaker and Word documents (other people have taken over the structured work), I really miss the XML-based tools. So, I would say don’t see XML as a threat — it is an opportunity. And don’t forget that it is the content, and the structure of the content, that matter. Introducing fancy tools will not compensate for bad technical writing. C

Gillis Rudh is a technical author with Citec Information, a provider of technical communication and localisation services. E: [email protected] W: www.citec.fi

Remember that ISTC members qualify for a 25% discount on British and

international standards. For a list of relevant standards, visit:

www.istc.org.uk/pages/standardstoc.php

To order, e-mail [email protected]

The freedom for the individual technical writer was already very limited. The idea was to create consistent information, even if many technical writers were involved in writing a set of books.

We young and ambitious writers, employed to write technical manuals for the then-new combat aircraft called ‘Viggen’, disliked the restrictive roles that kept us from communicating. At that time, we did not see what our superiors saw — a consistency in all information given out to the users. However, we soon discovered that the roles focused only on the general structure and how to use certain words (and, of course, avoid others that were on the customer’s black list). There was very little focus on content, or on the structure of content, and none whatsoever on how to present information in an easily understandable way for a certain audience.

Today, we have full focus on the communi-cation task, the audience to address and the methods to use. So, generally speaking, technical writing has become more fun. However, some organisations still think: ‘OK, we will introduce XML and train people to handle a set of DTDs. That will solve our technical communication problem once and for all.’ Do you think it will?

The structured wayI started to work for Citec Information three and a half years ago. After a little more than a year, I was asked to work for a customer that was migrating from an unstructured FrameMaker environment to an XML-based structure. My mission was to supply the company with service manuals. After a short introduction, I began to use the Epic Editor XML editing tool (now Arbortext Editor). Although it was a new version, I had used the tool before. Some of you may have had bad experiences with early versions, but I really like it. For me, compared with FrameMaker, Epic is very easy to work with; it will not give anyone who is used to, for example, Microsoft Word any problem at all. The only thing is to pick up the correct DTD, which initially caused me some problems.

PreviewIn the beginning, it is natural to concentrate on the result and preview what you have done. You

www.componentone.co.uk .NET Documentation • Help AuthoringSALES: 0800 328 5271 • +44(0)1460 234636

VISIT OUR WEB SITE TO DOWNLOAD YOUR FREE TRIAL ©1987-2005 ComponentOne Europe Ltd. All rights reserved. All product names are owned by their respective owners.

LIMITED TIME OFFER: ROBOHELP USERS SAVE £125 ON DOC-TO-HELP ENTERPRISE 2005 v2 — ONLY £345 AFTER SAVINGS

Try our one-clickRoboHelp®

Project Converter

Get Started in Minutes with Doc-To-Help® 2005 v2

NEW FOR 2005 v2

It’s what’s next.

Authors converting to Doc-To-Help

experience minimum ramp-up time

when using Doc-To-Help’s exclusive

one-click project converters. Import

the RoboHelp project file, click

convert, and projects are completely

coverted to Doc-To-Help HTML or Word

source files. Project settings, formatting, and content are preserved.

See for yourself by visiting www.componentone.co.uk/oneclick2005

RoboHelp® Project ConvertersConvert your RoboHelp files, complete with all Help system features,into “build ready” Doc-To-Help 2005 v2 projects in just one click.

Feature Rich Help AuthoringCreate virtually any online Help system (including cross-platformHTML) and printed manuals from your Microsoft Word or HTMLcontent. Add advanced elements, such as dynamic effects, pop-uplinks, conditional text, automatic context IDs, and much more.Visit www.componentone.co.uk/2005 for the full feature list.

Subscription, Support, and ServiceDoc-To-Help 2005 v2 includes a one-year subscription service deliveringupdates and new versions as they are released, as well as free e-mail support. Telephone support plans are also available.

Technology RoadmapStarting with Doc-To-Help 2005, we’ve published and continuouslyupdated a roadmap so you will always know our plans for technologies such as XML and New Microsoft Help Formats.

Help Authoring in Any HTML EditorUse any HTML Editor, such as Microsoft FrontPage or Macromedia®

Dreamweaver®, to author your content and configure your Help system.Our unique markup allows you to use style classes to create fullyfunctional Help systems in the editor of your choice—no proprietaryeditor required.

NEW FOR 2005 v2

ENHANCED FOR 2005 v2

LATEST FEATURES IN 2005 v2RoboHelp Word and HTML Project ConvertersDreamweaver, FrontPage, and Word IntegrationExpress Interface for a Streamlined WorkflowDocumenter for .NET Support for Microsoft® Visual Studio® 2005NetHelp Output for Web DeploymentContext Sensitive Help for Web Applications

DOC-TO-HELP2005 v2

NEWVERSION

d2h05v2_a4_1205.qxd 12/12/2005 10:19 AM Page 1

Pity the poor hirerLooking at CVs from the recruiter’s side of the desk, by Colette Clenaghan.


1� Careers

Another article about CVs? Yes, I’m afraid so, but let’s start with this question: why is it that technical authors often fail to provide CVs that exemplify best practice?

There are plenty of websites and recruitment agencies offering advice on how to present a CV, yet many of the CVs that I have seen take no account of such advice. Even fewer show any evidence of the analytical skills that are supposed to be at the core of good technical communication. So here is the view from an occasional hirer, who has had the good (or bad) fortune to read CVs from programmers, system administrators and technical authors.

The CV as shop windowIt seems to me that some people send in CVs without thinking about the logic or context of what they are doing. Many authors do not appear to realise that their CV is their shop window.

To the hirer, a CV is the first demonstration of the author’s ability to present and communicate information in a specific way to a very particular audience. It is not only the vehicle for the candidate’s claims to be an author, it is itself evidence of those claims. If a candidate claims to be logical and organised, but the hirer has to jump to and fro, piecing together the information needed to assess the candidate’s suitability, how much credence will that claim have? The tolerance that may be afforded to a programmer or systems analyst over poor presentation is unlikely to be granted to an author.

Focus on the audienceThe primary audience for a CV is not a recruitment agency, nor a Human Resources department, but the hirer. So why doesn’t every author applying for a job think hard about that audience and present the CV accordingly? Of course some do, but far too many manifestly don’t.

Typically, hirers fit in recruitment around their main role in the organisation. Under constant pressure to complete projects on time, they seek someone to relieve the burden, but the process of finding that person adds to the stress that they are already suffering. Their goal is to find the right person for the job. The job hunter’s goal is get the right job, or at least a job. The two goals would be more likely to coincide if only the applicant did what an author is supposed to do, and made it easy for the hirer to realise his or her goals.

These days a hirer may receive dozens, if not hundreds, of applications for one vacancy. If the average length of the CVs is around six pages, two dozen applications add up to over 140 pages — enough to turn anyone’s brain to porridge.

You can begin to see why two pages are so often regarded as the optimum length to aim for in a CV. Whatever their length, the hirer has to wade through all the CVs, assessing their merits and drawing up a short list of candidates for interview.

A CV does not need any fancy tricks to stand out; it just has to be clear, succinct, easy to follow and easy on the eye. So, for authors who are job hunting, here are some pearls of wisdom, born from the irritation of experience and intended to help make the hirer’s lot a happier one.

A string of pearlsNever use a third party to write your CV. If you

can’t present a few pages in clear English about a subject you know intimately, what are you doing masquerading as an author? If, in a moment of weakness you do succumb, go over the resultant document with a magnifying glass. Check everything, word by word, line by line, section by section. By the end of it, you will wish you had written the CV yourself. Any errors in facts, structure, grammar, syntax, layout, punctuation, capitalisation or hyphenation will be attributed to you; if you blame the CV company, where does that leave your claim to be an author?

Don’t leave gaps in your CV. Whether there are ten years missing, or just a few here and there, they immediately raise questions, if not doubts. At best, what were you doing then? At worst, what is it about those years that you don’t want to talk about? Were they spent at Her Majesty’s pleasure? Did you have to do a bunk abroad to lie low for a while? Was the time spent bumming around? It may not be pertinent to the job, but you can save the hirer from speculating. A very short sentence can summarise the time that you regard as irrelevant.

Make no assumptions about what is significant. When I applied for my second computing job after three or four years as an analyst/programmer, I didn’t make the mistake of leaving gaps, but compressed into a single sentence my many years of teaching abroad. That sentence secured me an interview. I had not known when I submitted my CV that the publishing house had a subsidiary specialising in books for learners of English as a foreign language. My teaching experience struck a chord with the hirers.

At the same time, exercise judgement. Not all of your experience is of equal worth. If you are applying to a large organisation, don’t give the same prominence to a three-week contract for a one-man band as you would give to a three-year stint with a blue-chip company. They are not of equal value, and it’s obvious which one the large

‘A CV does not need any fancy tricks to stand out; it just has to be clear, succinct, easy to follow and easy on the eye.’


17organisation will be more interested in. If you are moving from academia to the commercial world, how relevant is page after page detailing every paper and article you have ever published? However, don’t leave out important skills that might be relevant to your application. Ideally, of course, you would write an individual CV for each job. Just as in clothing, where the one-size fitting beloved by manufacturers results in clothing too large for some and too small for others, so a one-size CV will result in your not appearing to be the ideal candidate: you may be considered too experienced or too expensive for one job, but too inexperienced for another.

Make the nature of your experience clear. If a three-month job is vacation work or a work placement for a qualification, say so. If your experience is through a hobby, say so. I once received a CV in which the applicant claimed six years’ experience of C programming. It was exactly what was wanted, until it became clear that he was barely out of his teens.

Put dates on everything that needs them. Don’t make hirers work at being detectives to assemble a picture of you and how well you fit the ideal profile for the job. If you don’t give dates, hirers have to work them out and will not be grateful that you forced them to spend longer on your CV than planned; more likely, they will toss it straight into the reject pile.

When applying for a job in IT, give versions for the software, operating systems and programming languages you have used. This

may be particularly significant when legacy systems are being converted or upgraded. A particular version may have been specified in the job description, but omitted from the advertisement. Even if the job is not software-related, indicating versions shows attention to detail — a useful trait in an author.

Attend the interview with a copy of your CV. Firstly, the agency or HR department may have sent the wrong CV, or mangled your content and presentation, thereby worsening your chances. If necessary, you can show the original. Secondly, if you can’t remember what you put in your CV, you can avoid having to ask to see the hirer’s copy. Absent-mindedness may be a charming characteristic of a genius: in lesser mortals, it is correspondingly less charming.

Be honest at the interview. Don’t waste the hirer’s time by laying claim to knowledge that you don’t actually have. If you’ve forgotten something, say so. If you don’t know something, say so. The answer to a question such as ‘What programming language was used for the development of the software?’ is not ‘High-level code’. If there’s a good reason for not knowing, give it. You can then move on to something else.

Finally, if you provide samples of work (and any serious hirer will ask for them), make sure that they are as good as they can be. You may have an excellent excuse for any broken links, spelling mistakes and formatting faux pas. However, such errors will be quickly spotted, and none will leave the hirer with the right impression of you. C

Internationalizing

Product Information for the

Medical Technology Industry

Technical translations

Software localization

Online help

Layout and DTP

Translation Memory

Terminology

Coordination of review by overseas branches

Consulting and process optimization

mt-24 online project managementsystem

global-term online terminologymanagement

Challenge us. We look forward to it.

mt-g medical translation gmbhSchuetzenstrasse 1989231 Neu-UlmGermany

Voice:+49 7 31 17 63 97 - 42

Telefax:+49 7 31 17 63 97 - 50

E-Mail:[email protected]

Internet:www.mt-g.com

AnzeigeCommunicator_210x143_V1.qxd 14.01.2005 15:46 Seite 1Colette Clenaghan, an ISTC Associate and former teacher and programmer, is now an information engineer at NCR Corporation. E: [email protected]

Fruit and vegetables: a winning entry‘What on earth do you do in a supermarket?’ Pam Nicholl describes her work as a technical communicator in a retail environment.


1� Project profile

As an integral part of our drive for continuous improvement, the ISTC’s 2005 Documentation Awards became the Branch Operating Procedures (BOP) team’s project for last year. For me, it presented a time to reflect that my career development in Waitrose has really been one long project in itself. It has been challenging, very hard work, lively, innovative and vibrant. There is always a new challenge, always the need to identify, improve, simplify, satisfy and move on.

The beginningI joined Waitrose as a Management Trainee with the intention of working my way up to branch management. The business was well organised and branch systems and processes worked smoothly, but very little was written down, apart from the financial and stock management elements of the operation. At that time, we were no different from any other retailer in this respect. However, more managers were being recruited as graduate trainees or from other industries and competition among supermarkets was, and still is, fierce.

It seems evident that, in a company where standards are of paramount importance, a new manager is far better equipped to maintain consistency if all our policies and procedures are clearly expressed in writing and that they should be available for all branch Partners to refer to, rather than management alone.

These observations must have been well timed. A year into my first branch appointment I was asked how I would like to move to head

office for 12 months to ‘bring the procedures up to date’. This seemed an exciting challenge well worth taking up.

A time of changeI achieved my one-year deadline, but along the way I discovered I was on a mission. At our head office in Bracknell, department structures were changing. As branches increased in number, it was no longer practical to have regular visits from subject experts who contributed to the education process. It was going to become increasingly important to have all the elements of operational procedure clearly formulated to deliver change and evaluate its impact as we moved into the future.

It was also becoming clear that technical advances in our operating systems would raise the need for user guides and that, as legislation placed more demands on food retail, records and documentary evidence would need to become part of the daily routine. In fact, enforcement officers would soon be insisting on it. As is very likely the case in most companies, it was not always easy at first to convince colleagues of a need that had not yet strictly arisen.

The long-term projectThus, my long-term project began as Procedures Coordinator. This was quite a good description of the role at the time and consisted of getting to know department heads, understand their roles and interaction with our branches, and then move on to identify which further aspects of the branch operation needed to be documented and to what level of detail.

Having no background in this field but being a logical thinker and lapsed translator, I decided to begin by attending a two-day course on policy and procedures. This gave me a good, clear picture of where I felt we should be. I started identifying those components of the branch operation that were not documented or were poorly understood, and worked out a new structure to demonstrate how it could work.

After establishing contact with the various subject experts at head office, I visited a number of branch managers to identify what might help them to do their job better. Some highlighted the need for more detailed procedures and some quite the opposite. It was interesting to discover what was custom and practice and what was actual company policy.

As a relative newcomer, I was able to ask without embarrassment any question that came to mind because there was no expectation that

‘…a new manager is far better equipped to maintain consistency if all our policies and procedures are clearly expressed in writing…’

Pam Nicholl with Mark Andre, Department Manager Merchandise at Wokingham


1�I should know any of the answers. This is the first thing I now point out to new team members when easing them into their role.

During my investigation process I learned a great deal about the business. Waitrose was making major commercial strides at this time and the value of the policy, procedures and records structure began to prove itself as a sound commercial tool.

At the beginning, it was interesting to see how the sight of our own ideas in draft quite often triggered still better ideas, highlighted inconsistencies between one process and another and brought people together in the decision-making process. The circulation of draft work also saved a lot of unnecessary meetings!

LanguageFrom the outset I took the opportunity to change the style of the language. It had to be read and quickly grasped. It could be read by anyone: shop floor Partner needing information urgently, director, enforcement officer. This called for plain English in an unpatronising style. It was sometimes a challenge and I well remember that the path leading from ‘in the event that blah blah, branch mangers must ensure that blah blah.’ to the simple ‘when so and so happens, do this’ was winding and sometimes tortuous. Nevertheless, I achieved it by gentle persuasion, some persistence and occasional bulldozing. At the bulldozing stage, I was fairly firmly established as editor and usually writer of what had now become the Branch Operating Procedures.

Interestingly, I find even now that material I wrote only a couple of years ago can be simplified in its language. Such is the pace of evolution.

SoftwareSoftware was at first a challenge. The inherited procedures had been word processed and filed in brown plastic-coated volumes. They certainly did not shout ‘read me’. I wanted to make them more readable, and so I did some research on how people absorb the written word, line length and margins, and set out to look for some software that would enable me to index more flexibly. For example, I wanted the user to find how to dispose of their food waste correctly whether they searched ‘rubbish’, ‘refuse’, ‘compactor’, or even by the contractor’s name. I settled on FrameMaker, which I tracked down at an event in London, and rushed back to the office elated because it seemed to do exactly what I needed it to do. I constructed procedures and user guide templates that served me well for several years.

The BOP team’s workThe role developed more or less as I had hoped and, as the procedures proved their usefulness, a small team began to develop. Now we are the BOP team, involved in almost every new

project that affects the branch operation. Each member has responsibility for an area of expertise. Overlaps in role are maximised to the point where a second person has enough under-standing to provide support in an emergency.

We have managed to maintain and improve our standards year on year by keeping pace with technology but above all by listening to our ‘customers’. These are Waitrose Partners at head office and in over 170 branches who come from all walks of life and every level of education. We are all pieces of the jigsaw and we aim to make every piece a perfect fit.

Systems and processesSeveral members have asked what on earth I do in a supermarket, so you would not be the first to do so. But think how your shopping reaches your trolley. There are numerous systems (ordering, distribution, ticketing, scanning, electronic communication) and, more recently, many developing handset applications that enable us to track our stock, check that our price tickets match the price at the checkout, reduce stock to clear, amend our orders and obtain sales and wastage information.

We produce user guides for all these in collaboration with our training department and technical teams. We often help with system design, using our knowledge of current systems and processes combined with what we know we need to keep life simple, improve productivity and provide us with the necessary information.

Due diligenceI mentioned the need for records to provide documentary evidence. Legislation makes a significant impact on the food retail industry. Imagine a counter full of sumptuous delicatessen and cheeses. For me, this represents strict open food handling procedures, refrigeration temp-erature monitoring, hot and cold product probing, cold chain from supplier to checkout, cleaning rotas, separation between cooked and raw food and various kinds of date coding. For me, this means policies, procedures, schedules, records and internal and external audits with all they entail.

It’s my role as Manager of the BOP team to be responsible for the whole due diligence package,

‘…as legislation placed more demands on food retail, records and documentary evidence would need to become part of the daily routine.’


20 Project profile

including liaison with Trading Standards, Environmental Health and other enforcement officers. We record and log every branch visit and follow up on all issues, many of which are simply queries as to how we operate and train. We meet regularly with our Home Authority TSO and EHO at Bracknell Forest and this provides valuable support for our business.

I am now also responsible for all licensing, such as Registration of Food Premises, Game (the animal kind) and Liquor Licensing.

Imagine a perfect moment of relaxation with a glass of your favourite wine. For me, that represents Liquor Licensing Act 2003, appointing and tracking some 400 Personal Licence Holders, submitting Premises Licence applications and variations and dealing with Police and Trading Standards Test Purchases. This is the stuff our job is made of.

Risk assessmentA few years ago, we designed a weekly branch self-assessment, which is a set of questions covering all the highest risk areas of our operation (for example, customer service, finance, health and safety, food safety). These self-assessments are completed in every branch and, by a filtering process, the business is provided with an accurate picture of issues arising and progress made. Any procedural change or new project is likely to cause these to be reviewed. Procedures have to be followed carefully in the team so that anyone making changes ensures that every single aspect of the process is covered. This does not become easier as the team grows larger!

Archiving is also essential because, for legal reasons, we need to know which procedures were in force at a given time (for example, in the event of an accident). So, in effect, the team needs its own risk assessment process too.

BOPonlineBOPonline is our affectionate name for the current Branch Operating Procedures, of which our Fruit and Vegetables was a small extract.

Our first online procedures were in PDF format, which was at that time a fair strain on the network and competed with important overnight traffic, such as price changes. So no contest there — a new solution had to be found.

Our branches are split into 10 groups and we set about researching what they and head office Partners wanted from the new BOPonline. We put the next phase to trial in several branches and sought feedback until we reached the most practical solution. We ensured that we had a good mix of computer-literate Partners and those who had not used the previous online version.

I was fortunate to engage a placement student from Coventry University. He came with us to Conference to help us choose and write a business proposal for the next generation of

software. BOPonline had to be available through our intranet, using the existing intranet search engine. The software had to be tested and approved by the Waitrose systems team.

We chose AuthorIT, imported all our existing material using a MIF importer, and launched it in June 2004. Needless to say, it was not quite that straightforward. Looking back, though, it was relatively painless. After comprehensive trials, the upgrade was launched overnight with an internal advertising campaign and plenty of BOPonline mouse mats showing basic instructions.

User guides are also online, but we do provide hard copy versions too, as we find technical information more difficult to absorb online. Handset applications are designed to take the user through step by step and need little else.

Work in progressWe are now spending all our free moments house-keeping. This consists of tidying up, working on our graphics which still need improvement, checking our links, and ensuring single sourcing wherever possible. Some repetition still remained from the old hard copy, where it was better to repeat text than cross reference to other volumes. Until this housekeeping is completed there will be too many search results, which doesn’t encourage searching and does encourage overuse of the telephone. We need to be in a position to give the best possible service by improving the ratio of development to support.

A good career?There must be so many paths we can take if we have genuine curiosity, a strong desire to interpret and improve, insistence on accuracy, and good verbal and written communication skills. As a technical communicator, unqualified except by experience and self-motivation, the observation I would most like to make is that my job is about people. Software is one of my best tools but I will never allow myself to be driven by it. It has to adapt to our needs — we shouldn’t have to compromise to make them fit.

It was quite by accident that I became a technical communicator. In fact, it was only at my first ISTC conference that I discovered my new identity and the subsequent networking has been invaluable. Training and education for our profession will surely bring enormous advantages to future communicators. It will be how we combine this training with the ability to predict and meet people’s needs that will prevent us from placing too many limitations on our own prospects.

One of the first things I say to a new team member is ‘ask “why” and “what if” to every piece of information you are given until there are no more whys or what ifs to be asked. Then you will be sure you have got to the heart of the matter. Only then you can you start to challenge and push the boundaries’. I think it worked for me. C

Pam Nicholl MISTC joined Waitrose as a Management Trainee in 1986 and is now Manager, Branch Operating Procedures. After studying at the Secretarial College of the French Institute in London, her previous career spanned from freelance translator and Director’s secretary in a French Commercial Bank to off-licence training manager specialising in the wine trade. E: Pam_Nicholl @waitrose.co.uk W: www.waitrose.co.uk

‘…the observation I would most like to make is that my job is about people.’

With an increasingly competitive global marketplace, communicating clearly and consistently in the language of your customer is vital. But writing for global markets is not easy and inconsistencies in source content can delay international product launches and damage your global brand.

SDL AuthorAssistant is innovative new technology that empowers global authoring. Now you can:

• Leverage previously written content from anywhere in the business• Easily find and apply approved global terminology• Automatically perform checks against corporate writing standards

And all this without changing from your familiar authoring tool, such as Microsoft Word, Adobe FrameMaker, Blast Radius XMetaL and Arbortext Editor.

To learn how you can put the world at your fingertips visit: www.sdl.com/author

Writing for global markets?Bring the words of the world to your fingertips

SDL International is the world’s leading provider ofglobal information management (GIM) solutions.

Finding common groundYvonne Cleary explores the overlap between accessibility and internationalisation in website design.


22 Translation

IntroductionThis article examines how the Web Content Accessibility Guidelines (WCAG), published by the Web Accessibility Initiative (WAI), are also relevant to the internationalisation, and sometimes subsequent localisation, of websites. Internationalisation is the process of removing local bias to make websites usable for visitors from all locations, while localisation involves tailoring content to suit a specific location.

The main goal for all readers of technical writing is accurate and efficient comprehension. However, readers have different competencies, skills, levels of prior knowledge and expecta-tions: consequently, their experiences of using documents vary considerably. While many may understand and be able to use a text with relative accuracy and efficiency despite problems with organisation, style or layout, the same text can pose severe difficulties for other user groups.

The digital divideAccording to the World Wide Web Consortium (W3C)1, the Web is the fastest-adopted technology in history. People without access — including special-needs users and users who do not speak English, the predominant language of the Web — can fall behind, or lose touch completely with, new technologies: this phenomenon is referred to as the digital divide. Neither special-needs users nor non-native English speakers feature prominently in discussions of the digital divide, which are more likely to focus on users in underdeveloped regions of the world or from underprivileged backgrounds.

The text of the Americans with Disabilities Act (1990) states that ‘some 43,000,000 Americans have one or more physical or mental disabilities, and this number is increasing as the population as a whole is growing older’. As the online population ages, the number of Internet users with disabilities will increase too. However, providing access for special-needs users can increase web development time and expenditure on a project, and is perceived to be a complex and unnecessary proposition. Likewise, although many websites are localised, most are not, because of the costly and often technologically and logistically challenging localisation process.

Imperatives for changeIn spite of the obstacles, organisations must improve access to their information to adhere to requirements both for language provision and accessibility, and to take advantage of the

economic potential of new markets. In the US, 43,000,000 special-needs users is a sizable market by any standards — almost 15% of the population. In Europe, accessible and localised websites could potentially reach vast untapped markets.

Federal and international guidelines describe ways to increase web accessibility: in many jurisdictions, such guidelines have become legal standards. For example, websites for US public bodies must adhere to accessibility guidelines set down in Section 508 of the Rehabilitation Act.2

Purpose of the guidelinesThe WAI is one of four domains of the W3C. It publishes guidelines for website developers to help them ensure that their sites are user friendly and accessible, and these guidelines are largely accepted as the de facto international standard for web accessibility. The WAI is supported by, among other bodies, the European Commission’s Information Society Technologies Programme. The underlying principles of the guidelines are also objectives of internationalisation projects:Separate structure from presentationMake content understandable and navigable.

Impact on internationalisationTo achieve each of these principles, the WAI lists 14 guidelines designed to make it easier for users with assistive technologies (such as screen readers or Braille displays) to browse websites. The WAI points out that: ‘Accessible websites can benefit people … who are not fluent in the language of the website. Specifically, many of the aspects of web accessibility for people with cognitive disabilities help people who do not know the language well’.

Understanding the guidelines and their objectives is a first step in determining how they can be implemented. Table 1 explains those that are most obviously relevant, and shows how they improve accessibility for special-needs users and how they can facilitate internationalisation.

Impact on localisationInternationalisation alone is not always enough. There are legal imperatives for localising instructional material, such as the EU Machinery Directive that requires instructions to be translated as necessary for the language of the target market (TCEurope, 2004). Table 1 identifies areas in which complying with accessibility guidelines can contribute to successful localisation (which is the subject of this issue’s translation page on page 49).

Notes1 W3C is international body with the mission ‘to lead the … Web to its full potential by developing protocols and guidelines that ensure long-term growth for the Web.’ See: www.w3.org.2 Section 508 ‘requires that Federal agencies’ electronic and information technology is accessible to people with disabilities’. See: www.section508.gov.3 The LISA (Localisation Industry Standards Association) OSCARs are the best-known standards in the localisation industry.


2�

ConclusionsThe WAI outlines the benefits of improved accessibility to electronic content: social, technical, financial and legal. Most of these benefits also apply to internationalisation and any subsequent localisation projects. Accessi-bility and internationalisation both address groups of Internet users who might otherwise be marginalised. While social duty may not always make inclusive initiatives a priority, direct cost benefits (through access to new markets) are possible while providing linguistically, culturally and technologically accessible websites to the widest possible audience. Furthermore, it may be important for bodies implementing and developing relevant standards (such as DITA — the Darwin Information Typing Architecture — and the OSCAR3 standards set

out by the Localisation Industry Standards Association) to examine elements of the guidelines for issues of common concern. C

References (accessed January 2006)TC Europe (2004) Usable and Safe Operating Manuals for Consumer Goods: A Guideline. www.tceurope.org/pdf/securedoc1_04.pdf

US Equal Employment Opportunity Commission (1990) Americans with Disabilities Act of 1990 www.eeoc.gov/policy/ada.html

US Government (2005) Section 508. www.section508.gov

Web Accessibility Initiative (2005) Developing a Web Accessibility Business Case for Your Organization: Overview. www.w3.org/WAI/bcase

World Wide Web Consortium (2005) Web Content Accessibility Guidelines. www.w3.org/TR/WCAG10

Yvonne Cleary is a Junior Lecturer in Technical Communication at the University of Limerick. She has an MA in Technical Communication and is Course Director for the Graduate Certificate and Graduate Diploma/MA in Technical Communication. E: [email protected] W: www.ul.ie

Table 1. Impact of WAI guidelines on accessibility and internationalisation/localisation

Guideline Explanation Increases accessibility because it

Facilitates internationalisation/ localisation because it

Provide alternatives to auditory and visual content

Requires the designer to provide text equivalents of non-text content (such as graphics, audio or video): an example is the alt text explanations of web graphics.

Enables users with auditory or visual disabilities to access alternative text to understand the message.Improves access for users with older technologies.

Improves access for users with older technologies (who are more likely to be in developing countries).Enables translators to translate text strings (such as alt text) where translating the graphic, audio or video might be impossible.

Do not rely on colour alone

Enables users who cannot see colour to understand the message fully.

Enables users with deficient colour vision to use content correctly.Enables users with monochrome displays to understand the message.

Ensures that cultural perceptions of colour do not hinder absorption of message.

Ensure that documents are clear and simple

Requires language that is easy to understand, with recognisable graphics and consistent page layout.

Helps users (including those with cognitive difficulties) to understand content.

Facilitates accurate translation.

Use mark-up and style sheets and do so properly

Highlights the importance of separating content from structure: ‘Control presentation with style sheets rather than with presentation elements and attributes’.

Ensures that presentation is controlled.

Ensures that formatting is unchanged on different platforms, systems and software versions.

Clarify natural language usage

Requires the writer to identify the predominant text language and write out abbreviations and acronyms.

Enables users and assistive technologies to identify foreign text or abbreviations.

Ensures that translators recognise foreign text and can make appropriate choices about how to render it in the target text.

Create tables [and pages using new technologies] that transform gracefully

Requires the designer to mark up tables and other media elements correctly so that they will look the same on different devices or systems.

Ensures that content in tables and new technologies can be recognised and correctly read by assistive technologies (such as Braille and screen readers).

Ensures separation of structure and content, thus preventing translation from altering the structure, appearance or content of the message.

Ensure user control of time-sensitive content changes

Ensures that moving, blinking, scrolling or auto-play contents can be stopped or paused.

Ensures that users can use the information at their own pace.

Ensures that non-natives have sufficient time to view content in foreign languages.Allows for cultural differences in how people read and use information.

Provide context and orientation information

‘Grouping elements and providing contextual information about the relationships between elements can be useful for all users’.

Helps users understand complex information or page elements.

Helps translators and non-native users to make sense of information.Makes information less likely to be culture-specific.

Provide clear navigation mechanisms

Ensures orientation information, navigation bars and site maps help people find what they need

Increases the flexibility of the site, making it more accessible to users from different cultural groups who might have different expectations of structure and layout

Terminology management in focusSo, you’ve decided to manage your terminology: Eline Beun suggests where to start.


2� Translation

Improving the quality of information and communication is a key focus for many organisations. One of the foundations of effective communication is terminology, which is the totality of brand names, technical terms, abbreviations and jargon that is specific to an organisation or industry. It is an area that is largely ill-defined and unnamed and the specifics are often learned on the job. By way of example, how you interpret the meaning of ‘float’ will depend very much on whether you are a web designer, a banker or a car mechanic, not to mention milkman or barman (root beer float, anyone?). However, how we interpret and understand a term is critical in the contemporary information world.

Information demandsToday, organisations are dealing with increasing, and potentially overwhelming, amounts of information. This excess of meaning is generated because of new needs for and means of creating and disseminating information across continents and languages. Externally, clients demand more and better information at shorter and shorter notice, requiring organisations to create yet more information and set up new systems and information delivery models. Another change factor is the development of new output channels, such as websites, FAQ overviews, help-desk decision trees and intranets, which require new processes for information control, quality assurance and updating.

What is terminology management?Terminology management procedures differ between organisations but, in essence they comprise one or more of the following steps:Identification, definition and capture of

terminologyTranslation and approval of terminologyDissemination and control of multilingual

terminology information.These steps need to be supported by suitable software tools and workflow procedures, and must be embedded in an organisation’s information processes in order to take it beyond a one-off action and make it a continuous process.

Lack of terminology managementOne public consequence of a lack of terminology management is the frequent faux pas to be found in brand names, where cultural aspects are not taken into account. For example, ‘Fast’ might be a product name for a high speed

controller, but the marketing manager who came up with that might not be aware that in German this means ‘almost’! And the liqueur ‘Irish Mist’ may not sell too well in Germany, where ‘Mist’ means ‘manure’.

On a more serious note, and one that can directly affect the corporate balance sheet, is the confusion caused when spare parts, say, have different names or even part numbers within one organisation. The frustration of the reader of the user’s guide is directly proportional to the loss of future revenue. Poorly managed translation may play a role here as well, but often the root problems can be traced back to the creation of the source text and to lack of terminology management.

Getting it right the first time is the only approach for terminology management. The costs of changing terms or making them consistent retrospectively are considerable, having consequences for information, ranging from the user manual, maintenance manual, quickstart guide to the website and catalogue, and across different media such as PDF, hardcopy, help files, websites or databases. Clearly, costs multiply considerably as a result of the wealth of information and the range of delivery methods. And yet these are often hidden costs, masked by the very lack of terminology management. It is difficult to measure something that is not there.

What are the benefits?Getting it right first time is never the easiest or cheapest approach. So why try to get it right first time? First of all, terminology management allows global branding of products and messages. This provides focus for the business and its employees by driving home a uniform message. By affecting the entirety of an organisation’s information base, terminology management fosters a culture of individual responsibility through employee buy-in to content development.

Further, it supports the authoring process in that it requires authors’ awareness of term identification and definition, and establishes a review process of source terminology and its translation, strengthening the uniformity of the message. Terminology management allows flexible projects within a larger organisation, for example tackling terminology problems experienced by a helpdesk or by the software development department. It provides a focus for rethinking the quality of an organisation’s whole information process, and more importantly, how

‘Focusing on terminology management … can help reduce turnaround times for information creation and translation.’


2�to measure that quality.

It is tempting to advise organisations to start from scratch, implement an entirely new terminology management system and change their procedures completely. But reality teaches us that, no matter how attractive in theory, it is a route that they are unlikely to take. Rigid, centrally managed procedures cannot suit the individual needs of countries, divisions or people. Terminology management is complex, and trying to convert a complex set of needs into a simple solution is bound to fail.

Successful terminology management needs key management support and a number of well-chosen initiatives to create success. One example of a well-chosen project is the creation of self-maintained, multilingual terminology databases for helpdesk personnel, enabling them to store and retrieve pragmatic terminology used in their everyday client interactions. Another example is multilingual terminology support for a new product marketing campaign; when built in from the start, this actually helps drive the global sales effort.

What about the risks?An organisation-wide approach that focuses on individual needs at the same time will have to take certain risks into account, such as lack of adoption of the new process or system by the end-users, selection of the wrong software tool or changing business requirements. These risks are real and need to be addressed by extensive communication before, during and after the implementation of a new system.

Whether it is terminology lists, a workflow system that manages terminology review, authoring tools or translation software, it is important that the user is not faced with a multitude of tools, and that information can be easily found, and feedback can be given. This level of buy-in, from managers as well as the terminology users, is key.

Focus areasAs terminology management involves the complete information process of any organisation and touches all departments and divisions, there are several areas that require attention. Focusing on these areas can bring measurable results within reasonable time frames.Authoring support — providing rules and

guidelines for establishing what can be defined as a term, creation of definitions, providing context, usage labels and grammatical information

Controlled language — creation of approved terminology sets for controlled authoring

Terminology mining — the identification, description and capture in a system of termin-ology from monolingual or multilingual corpora

Review — recruitment and/or training of in-country reviewers for translation of terminology

Terminology tools — depending on the needs, there is a wide range of terminology tools available, from pen and paper, spreadsheets to integrated workflow systems

Translation — providing translators with approved terminology, preferably stored in a database that will prompt correct usage

ConclusionFocusing on terminology management is beneficial for most organisations. It highlights quality and stimulates involvement of all players in the organisation’s information process. It can help reduce turnaround times for information creation and translation, bring about a consistent marketing and sales message and reduce costs through more streamlined processes, less rework and fewer demands on helpdesks.

While the best approach may be organisation-wide, tangible benefits will come from individual projects that address and solve actual business issues. C

Create effective localised versions of your software,web presence and documentation

Improve your time to market

Reduce your localisation costs

Reflect the quality of your products across all languages

Looking for a Technical Language Solution?

We’re talking your language - Call us today on01829 730050

www.lloyd.co.uk

Lloyd International will help you:

an ISO9001:2000 certified company

Lloyd_advert_2006_white.qxd 1/2/06 10:27 am Page 1

Eline Beun is Account Development Manager with Lloyd International Translations, provider of solutions that combine terminology management, authoring, translation, localisation and information publishing. With a degree in German and English from the Maastricht State School of Translation and Interpreting in the Netherlands, Eline has spent 15 years in the localisation industry. E: [email protected] W: www.lloyd.co.uk

S1000D-compliant illustration filesDavid Manock describes how this technical publications standardaffects the creation and delivery of illustration files.


2� Illustration

IntroductionS1000D is a standard that controls the creation and delivery of technical publications. Although the standard applies to all publication elements, this article focuses particularly on its impact on illustration files.

If you work in the military or aerospace sectors, you may already be familiar with S1000D. Its profile has been raised recently by its proposed adoption by the US DoD (Department of Defense). In Europe, the story is very different: defence ministries and prime defence contractors have used S1000D successfully for many years on various projects, including Eurofighter (Figure 1).

There are several reasons for the growing influence of S1000D, with two being particularly important. The first is the emergence of many more multi-country military projects, where one standard is preferable and cost savings can made by unifying information. The second, and probably more compelling for suppliers, is the mandating of S1000D by the defence ministries; in other words, you have no choice but to supply documentation that complies with the standard.

The impact, financially and organisationally, of S1000D can be substantial. It requires new skills to be developed by those writing, illustrating, managing and delivering technical publications.

History of S1000DS1000D emerged in the early 1980s, with the purpose of developing a global standard for technical documentation, similar in philosophy to the civil airline standard ATA100. Most early applications of S1000D were in military aerospace projects. Although the standard could be adopted by other industries, this has not yet taken place.

The main reason for the bias towards aerospace was that S1000D was originally developed to support air vehicles and their support equipment. This has changed, with S1000D now supporting land and sea equipment, as well as air.

Primarily a European standard, governance is provided by ASD (the Aerospace and Defence Industries Association of Europe), which was formerly known as AECMA (Association Européenne des Constructeurs de Matériel Aérospatial). The involvement of the USA has required additional transatlantic governance of S1000D; this is provided by the AIA (Aerospace Industries Association). However, ASD and the AIA do not develop or maintain S1000D. This task is in the hands of specific councils and working groups. Figure 2 shows an overview of the organisation.

The latest significant development is an investigation, being carried out by representatives of the ATA (Air Transport Association) and the S1000D

organisations, to determine the feasibility of merging the civil standard iSpec2200 with S1000D. This is an ironic twist, considering that one of the prime reasons for developing S1000D all those years ago was in response to the ATA standard of the time.

Principal concepts of S1000DThe S1000D standard is a substantial document, containing over 2000 pages. The current version is Issue 2.2, with the next release due in mid-2006. The defining concept that separates S1000D from other documentation standards is the Data Module, a chunk of information utilised to support the equipment in question. A Data Module can contain different information types (such as descriptive, procedural and fault diagnosis) to aid the maintenance of the equipment or even the business rules for managing the project.

The traditional technical publication is usually a manual or suite of manuals with a linear structure, containing chapters, sections and pages. S1000D has a modular structure; this is based on Information Sets, which are collections of Data Modules, categorised under general headings (such as maintenance, operational and illustrated parts data). The modular approach

Figure 2. S1000D organisation chart


27provides the opportunity to reuse, manage and deliver information using contemporary methods and tools.

The information contained in a Data Module is identified by a unique code (Figure 3) that specifies details such as the assembly, sub-assembly, disassembly sequence, and the information type. The main

function of the code is to enable data to be

easily identified and managed in a Common Source Database (CSDB).The CSDB is the repository for

the Data Modules. In addition to managing the data, it can also contain completed documents on paper or electronic media (including PDF and IETM — Interactive Electronic Technical Manual). The CSDB is also used to manage other data associated with the project including illustrations, which are usually archived in the CGM (Computer Graphics Metafile) format. Figure 4 shows an overview of the publication process.

Information creationThe philosophy of S1000D has always been to base the creation of data on internationally recognised standards. The production of Data Modules can use either SGML (Standard Generalised Mark-up Language) or XML (Extensible Mark-up Language). As stated earlier, illustrations should use the CGM format. The standard supplies relevant DTDs (Document Type Definitions) and schemas to aid the generation of Data Modules. These can be downloaded, along with the standard document itself, from www.s1000d.org.

The structure of a Data Module is divided into two distinct parts:1. The Identification and Status section

contains mainly meta-data. Primarily used for managing the Data Module,

the information includes the code, revision, quality assurance details, manufacturer’s name and security classification.

2. The Contents section contains all the information needed

by the user to maintain the

equipment. Possible information types include descriptive, procedural, fault diagnosis and illustrated parts data.

If you are required to work to S1000D, you will be obliged to use an SGML or XML editor. The easiest option is to use an S1000D-specific plug-in providing instant compliance. You could try to implement this internally but doing so will incur time and cost overheads for your company.

S1000D-compliant illustrationsA section of S1000D that is sometimes

YY - Y - YY-YY-YY - YYY - YYYY - N

ModelIdentification

Code

SystemDifference

Code

StandardNumbering

System

Disassembly & Variant

Code

Information & Variant

Code

ItemLocation

Code

The minimum number of characters allowed in the code is 17 the maximum 37.

System Sub-System Unit

Figure 3. Data Module code structure

Figure 1. Eurofighter Typhoon

© Eurofighter


2� Illustration

overlooked is the creation and delivery of illustrations. There are several factors you need to consider when creating illustrations or repurposing data from another source such as a CAD (Computer Aided Design) system.

The major consideration is whether you have the capability to generate and deliver CGM files with the correct profile. This will not be the case if you are using general graphics software, CAD or visual mock-up systems. The CGM file will usually be checked for compliance and so it is crucial that your file is in the correct format. Delivering a non-compliant CGM file could result in lost credibility and increased costs. The software you require to generate compliant files is specialist and the functionality is not available in mass-market tools.

Another, just as relevant, consideration is the ability to create and manage hotspots in illustrations. These are described opposite.

S1000D illustration processThe main points in creating S1000D-compliant illustrations are naming, style and format.

Naming is a very important factor, one that you should not overlook or underestimate. As illustrations cannot contain meta-data, an Illustration Control Number (ICN) is used to identify and manage the illustration in the CSDB. Up to 45 characters in length, the code contains similar information to the Identification and

Status section of a Data Module (for example, security classification and issue number). The ICN captures this information in the file name. Figure 5 shows the structure of the code.

The stated purpose of illustrations for use in S1000D is to amplify and clarify text, with the objective of shortening the explanations of functions and procedures. Guidance is provided on how to produce illustrations for presentation on paper and on screen. You will be required to follow rules in the illustration process, some of which are summarised below.The illustration must provide maximum

information for the end user, with particular awareness of the output media.

Illustrated parts must be clearly identifiable and annotated appropriately.

Location arrows, leader lines and annotations must be clearly shown and free from surrounding detail.

Use of two- and three-dimensional CAD data is discouraged; although in both cases the data will be accurate, it either does not convey information convincingly or includes too much detail. A simple technical illustration could easily solve both issues.

Illustrations should be created at a realistic but sensible size; if important sections are very small, they must be enlarged in a detail drawing to show information clearly.

Where possible, exploded illustrations must convey the correct disassembly order of the equipment to the maintainer.

If several identical parts are present, only one has to be shown — providing that the position and orientation of the other parts is clear.

Wiring or system diagrams, schematics and other charts where symbols are used can be described as illustrations; they are, therefore, required to follow the same rules of naming and delivery format.

Illustrations are to be created and delivered appropriately for their intended output format. Illustrations destined for print should normally

Figure 4. S1000D publications process

ICN - YY - Y - YYYYYY - Y - YYYYY - NNNNN - A - XX - X

Prefix

ModelIdentification Code

SystemDifference Code

StandardNumbering

System

Responsible PartnerCompany Code

Originator Code(NCAGE Code)

Sequential No.

VariantCode

Issue No.

SecurityClassification

The minimum number of characters allowed in the code is 27 the maximum 45.

Figure 5. Illustration Control Number structure


2�

David Manock is Product Marketing Manager at ITEDO Software. He qualified as a Technical Illustrator at Blackpool College (UK) in 1981 and has a wide practical experience of various aspects of technical communication. Instrumental to the introduction of IsoDraw to the UK market in the early 1990s, he has since acquired in-depth knowledge of the ITEDO product range. With extensive knowledge of graphics standards such as CGM and WebCGM, he is familiar with current developments in the ASD S1000D standard. E: [email protected] W: www.itedo.com

be portrait; landscape may be used on a foldout page but this must be described in the business rules for the project. If the illustrations are intended for an IETP, the format restrictions do not apply. However, if the illustration can be printed, its layout must be considered.

The use of colour is encouraged where the illustrations are to be delivered electronically and clarification of the information is required. However, a specific S1000D colour palette should be used to comply with the standard.

Figure 6 shows an example of a technical illustration created in accordance with S1000D guidelines. The detail drawing clearly depicts the location of the assembly on the vehicle. Showing the ICN on the illustration is optional, usually dependent on the project requirements.

Purpose and use of hotspotsHotspots are sensitive areas in illustrations, comparable to hyperlinks in documents. The term is used to describe a clickable area on an illustration that usually provides a link to navigate the technical publication. Creation of hotspots and subsequent delivery of illustrations are key requirements when the intended output is an IETM.

Hotspots can be used in various contexts. A hotspot can provide a link to text in a Data Module (for example, a parts list). It can provide a link to another area of the same illustration or an area of another illustration. The sensitive area can be the callout number or it can include the leader line and the graphic element itself.

The benefit of hotspots to the user is that they provide information in an intuitive environment. As well as facilitating easy identification of parts and assemblies, they provide means of graphical navigation in documents of a kind that is not possible with printed manuals.

The technology that enables the inclusion of hotspots is based on CGM; this file format allows you to include graphical meta-data, which provides the ability to describe a hotspot ‘region’ and a target for the link known as a ‘viewcontext’. To create this information, you need specialised illustration tools developed specifically for this purpose.

Delivery of S1000D-compliant illustrationsThe final task is to deliver your illustrations in a compliant CGM format. S1000D utilises a cascading profile based on WebCGM 1.0, Second Release, which is a recommendation of the W3C organisation. The WebCGM format is developed and maintained by CGM Open, a non-profit organisation comprising representatives from software vendors, industry and government. The S1000D organisation uses only a subset of the complete WebCGM profile, which is why it is described as ‘cascading’. These recent developments should provide a good basis for the future maintenance of the format.

Importance of S1000DIn summary, while S1000D is not applicable to every industry, some aspects of its methodology could benefit your company’s documentation process. The key benefit for a company imple-menting the standard is the creation of data in a structured neutral environment, ensuring data will always be accessible and easily managed throughout its life cycle. The key benefit for the company’s clients is the provision of a user-friendly environment, especially when information is delivered as an IETM.

The provision and delivery of illustrations is a key part of any technical documentation process, providing major benefits for users both in understanding and navigating the documentation. The generation of illustrations should not be overlooked, especially in environments where stringent standards have to be considered. C

Resourceswww.s1000d.org Organisation that maintains the overall standard.

https://ussmg.btas.com/default.aspx New official group based in the USA that is also contributing to the maintenance of the standard.

www.asd-europe.org/Content/Default.asp Organisation that governs the European operation.

www.aia-aerospace.org Organisation that governs the USA operation.

www.cgmopen.org Organisation that maintains the WebCGM file format.

www.w3c.org World Wide Web Consortium, which develops inter-operable technologies to achieve the Web’s full potential.

ICN-G3-A-042000-A-D1871-00001-A-00-2

11

8

610

5

7

5

4

3

9

2

1

Figure 6. Example of an S1000D-compliant technical illustration© Stork PWV, Boxer Military Vehicle.Illustration with kind permission of Continental Datagraphics, UK.

Programming: the wheel of fortuneIn the final part of his series on computer programming, Anthony Seaton tries to predict the future.


�0 Software

Short of gazing into a crystal ball, careful analysis of current trends and their history is perhaps the most reliable indicator of what the future holds. Current trends in software are being driven by changes in hardware systems topology and infrastructure (Figure 1).

The mainframe may now be reaching the end of its life. It is being replaced by smaller, faster servers, sometimes networked into clusters for resilience. That is not to say mainframe development has ceased, as the largest processors continue to grow. Meanwhile, on the desktop, growth in storage, speed and reliability also seems set to continue.

With mainframes and servers at the hub, linked to desktop computers at the rim by network spokes, we can view the hardware environment as something like a wheel.

The hubThe massive Cray XT3 at AWE (Atomic Weapons Establishment) Aldermaston is probably the most powerful single machine in the UK, and argued by Cray to be the most powerful in the world. This is a claim that IBM might dispute, their contender being the blue gene. Apart from these beasts, almost the only mainframes now produced in any volume are those from IBM. These offer parallel sysplex, the means to divide the machine into logical partitions (LPARs), each of which can be assigned to run almost any operating system you care to show it. There is no restriction here, either to prehistoric legacy systems or cutting-edge development. This offers plenty of scope finally to move away from IBM’s own systems software and the associated costs.

The likes of Amdahl and ICL became part of Fujitsu, which has followed Sun Microsystems in the production of large-scale servers running Solaris on SPARC processors. Sun itself offers the Sunfire E20K, which ‘scales up to 72 processors with 144 threads and up to 576GB memory for heavily threaded commercial

applications’. Sun differs from IBM in offering world-class system software and development tools free, with plenty of scope for cutting-edge systems development.

One of the largest express delivery and logistics firms in the UK has retained its structure of IBM mainframe, HP Unix servers and PC front-ends, but has spent the last few years migrating from COBOL systems running under OS/390 on the mainframe and C++ under HP-UX on HP-9000 series servers, to running Linux across the board and redeveloping all of its software in Java. As well as improved performance, this has enabled a very considerable saving in software licensing costs. Running Suse Linux on an LPAR of its IBM z990 mainframe, it has switched to Red Hat on its HP servers.

At the centre, many large organisations are now migrating from mainframe technology altogether, replacing it with servers, super-servers and clusters.

Many small to medium-sized enterprises have taken the path towards object-oriented enlightenment, be it with C++, VB using objects, or Java. As new releases of Microsoft’s Visual Studio become more widely adopted, this trend looks set to continue. From where I sit, this is no bad thing. Object-orientation, when competently applied, can lead to very elegant software solutions.

At the database level, SQL is currently by far the most widely used query language. For the technical author, this means entity-relationship diagrams and subsequent representation at table and query level.

Programming at the back-end, server-side or back office (whichever is your organisation’s preferred term) is often done largely in-house. Code may be written in whatever language was popular when major changes were last made, from pre-Y2K legacy software to state-of-the-art, object-oriented offerings using advanced fourth-generation languages.

The spokesMore than ever before, software is key at the networking level. The concept of networking being simply cables, modems, racks and routers is history. A growth area, the network layer now includes all manner of software technology.

Internet technology is everywhere. Since most organisations would now be lost without it, most have seen the sense in using similar conventions within intranets of any significant size.

ASP (active server pages) web-tier code allows a higher degree of interaction with the host

Figure 1. Conceptual model to show three levels of hardware topology


�1server than simply displaying pages and running hyperlinks and crude e-mail tags at the client-side. Websites using ASP can be dynamically updated and enable users to run queries against a database on the server-side. Since the birth of its .NET paradigms, and particularly ASP.NET, ASP has tended to be uttered in the same breath as Microsoft.

XML (extensible markup language) works in a similar way but is wider ranging, being a cutting-edge W3C project. Described as ‘the glue that holds the whole thing together’, XML offers the power to communicate with the client or user through HTML, with a wide range of languages, platforms and applications on the server-side. It seems well oriented towards the future, its potential for interactivity with mobile telephones continues to grow, with the development of Voice XML, for example. Given the degree of artificial intelligence needed to identify words spoken in different accents, this is indeed a marriage of technologies crossing several schools of thought and programming paradigms.

Many organisations now boast quite elaborate intranets, which may be likened to in-house internets, ensuring that the most up-to-date information is available to every employee, from a staff handbook to a whole library of development or teaching resources. An intranet may also provide access to a large, central document repository.

The rimAt the rim of our wheel, some might say Microsoft is everywhere. Agreed, Microsoft is big, powerful, and influential. However, there are alternatives in the form of Macintosh, Unix, SPARC or Linux. The open-source movement is somewhat dichotomous; on the one hand, it wishes nothing more fervently than to perfect Linux as the antidote to Microsoft Windows, while on the other it seeks to make products like Open Office as Microsoft-compatible as possible.

For the web programmer, the user-end of web development is likely to see the further evolution of HTML, cascading style sheets and scripting languages, used for both Internet and intranets.

For the application programmer, love it or loathe it, there is little doubt that Microsoft’s Visual Studio is here to stay and has a significant future, especially with its evolving manifestations of VB and C. The latest .NET versions of Visual Studio aim to consolidate the principles of object orientation to a much greater extent. VB.NET and C#.NET are among the rising stars on the UK job market at time of writing. Visual J# (the Java derivative), however, has fallen rather flat. This appears to be good news for Sun Microsystems, since Java is still in greater demand than any other programming language.

That the demand for ASP.NET is about 22% higher than for ASP suggests that there is, at least, some mileage left in this incarnation.

However, I won’t commit myself to a prediction either way.

Will Microsoft ever achieve total domination? I consider it unlikely, given the proliferation of platforms hosting other operating systems. Will Microsoft be marginalised? Not in the foreseeable future, although one can only wonder what will become of a Microsoft without Gates.

The impact on authorsWith the advent of large-scale application of object-oriented paradigms, came the need for more sophisticated representation of require-ments analysis, process flow, collaboration, component deployment, sequence and structure than was available using traditional flowcharts.

Figure 2. UML use case model to represent a payroll system

Figure 3. Project development lifecycle


�2 Software

Ivar Jacobson and James Rumbaugh started to pioneer object-modelling diagrams in the 1980s and, by the early 1990s, were joined by Grady Booch with his use case models; these were to form the crucial initial-level systems analysis at the heart of the Rational Unified Process (RUP).

Figure 2 shows a Unified Modeling Language (UML) use case in which the arrows represent participation or ‘use’ of another construct within the model. At this stage in the process, data flow is shown only where the actors, or participators at the periphery of the software system are shown. It helps to think of this in terms of ‘I need to go to the bank for money’ rather than ‘money comes from the bank’.

As far back as 2001, I worked as technical author for a software house eager for my (then newly acquired) UML skills. For all that Rational processes and tools have now become part of IBM, many other companies, including Microsoft, support UML.

When used to its full potential, UML is much more than a planning and diagramming tool; it can enable some code to be created automatically. Some tools enable models and diagrams to be reverse-engineered; that is, created from automated analysis of program code. While, to my mind, this is rather like the student who, having developed a software solution, sketches out a hasty flowchart in the hope of scoring a few marks for planning and design, it can be useful in documenting projects for the benefit of future developers.

When writing for the full software system development lifecycle (Figure 3), this also leads to the need for some conceptual understanding of object-orientation (Figure 4).

Within this lifecycle, both at implementation and documentation stages, there is the on-going need for interactive help. Where the future is heading in this realm is unclear. Following the question marks that have surfaced around the future of RoboHelp, one can only speculate. From where I sit, I would suggest that whatever follows it will make use of some of the features offered by ASP or XML technologies.

SummaryThat the number of job vacancies requiring UML at the time of writing was some 15% greater than the number requiring ASP is, perhaps, indicative of the growing market for UML. For all that Microsoft played down the development of UML facilities when it acquired Visio, apparently abandoning the prospect of forward-engineering options, it still has some reverse-engineering features. The variety of freeware, shareware and commercial products suggests that there is a future for UML. There is certainly a need to understand something of the concept of object orientation, with fourth-generation object-oriented languages looking set to be around for a while.

On that score, the continued increase in object-oriented development means that languages like VB.NET, C#.NET, C++ with objects, and (currently above all) Java are likely to remain in high demand for some time.

Furthermore, the greater potential I have suggested for XML over ASP is strengthened by current demand for XML outstripping demand for ASP by a factor of almost 2.5.

Moving from fourth- to fifth-generation languages, while I would suggest that any possible explosion in the market for programming in the fifth-generation declarative languages associated with artificial intelligence might still be a little way off, there is certainly a great demand for SQL. Use of SQL alongside fourth generation languages, especially those in the object-oriented paradigm, continues to grow. Some familiarity with SQL, its associated entity-relationship diagrams (ERDs) and table models are surely a bonus in the knowledge base that a technical author can offer. C

Tony Seaton BSc MISTC has worked in computing since 1986, specialising in technical manuals (to ISO 9000) from 1994. This led to documenting full software development lifecycles, and writing user guides. At present, Tony is teaching A-Level Computing and GCSE ICT and Graphics to college students. E: tony.seaton @bcs.org.uk

Figure 4. An object model, showing how instances may both inherit properties from the class definition, and have instance-specific properties applied


��

LaTeX: an introductionLaTeX is a powerful but relatively unknown typesetting system. Mike Unwalla explains where it came from and what it can do.

Tools

LaTeX is a powerful typesetting system, used for producing scientific and mathematical documents of high typographic quality. Unlike WYSIWYG tools such as FrameMaker and Word, it uses plain text files that contain formatting commands. It’s big, open source, stable and used by many technical publishing companies. It’s also relatively unknown in the technical writing community. This article overviews LaTeX, and directs you to sources of information.

HistoryDonald E Knuth (www-cs-faculty.stanford.edu/~knuth) designed a typesetting program called TeX in the 1970s especially for complex mathematical text. LaTeX is a macro package that allows authors to use TeX easily, and uses TeX as its formatting engine. It is available for most operating systems; for example, you can use it on low-specification PCs and Macs, as well as on powerful UNIX and VMS systems. There are many different implementations of LaTeX.

The word LaTeX is pronounced ‘lay-tech’ or ‘lah-tech’ (‘ch’ as in Scottish ‘loch’ or just hard ‘k’), not ‘latex’ (as in rubber). In plain text, the typography is LaTeX. The sample document in the panel shows its typeset form.

The latest version is LaTeX2e, but because this article describes general principles, I just use the word LaTeX.

Who uses it?I first came across LaTeX in 1992, when fellow students were using it to write academic papers and theses. These days, it is widely used in the technical publishing industry for academic journals, particularly by mathematicians, physicists and other people who have complex notational requirements. For example, Elsevier, IEEE and the Royal Society all provide author guidelines for people who use LaTeX. One of my clients uses LaTeX to produce software documentation (see pages 18–20 of the Autumn 2005 Communicator) and so I needed to learn it.

Basic conceptsAn author writes a LaTeX input file in a text editor and then compiles this using LaTeX. An input file contains text and commands for processing the text. There are some conceptual similarities to a markup language such as HTML. However, a fundamental difference is that LaTeX

is designed as a page layout language, unlike HMTL which is functional markup. The whole point of LaTeX is to achieve perfect typographic output, which is not the purpose of HTML.

LaTeX produces device-independent DVI files, from which you can generate PDF and PostScript files using the utilities that usually come with a LaTeX installation. Typically, you can also create a PDF file directly, as shown in the next section.

There are GUI editors to help with creating input files, but many authors prefer to use high-performance text editors such as UltraEdit from IDM Computer Solutions Inc (www.ultraedit.com).

LaTeX is very fussy. A trivial mistake may mean that no output is generated and many error messages are displayed. You will need to check the error logs, fix the problem and recompile.

A sample documentThe example code is very simple. It is contained in a plain text source document called hello.tex. The first line specifies the type of document. There are various standard classes, such as ‘article’, ‘book’ and ‘letter’, with pre-defined features that can be customised. The third line is the body of the document. The \textbf command indicates that the text enclosed in parentheses is bold. The \textit command indicates that the text enclosed in parentheses is italic. You can see how it is possible to nest commands. The \LaTeX command produces the typeset form of the word. To produce a PDF file, I typed pdflatex hello.tex at the DOS command prompt. This generated a PDF file, hello.pdf, containing the typeset text.

Obtaining more informationLaTeX is far more powerful and far more complex than this simple introduction suggests. The Comprehensive TeX Archive Network (CTAN) is the authority for materials that relate to TeX and LaTeX (www.ctan.org). You can download LaTeX free from CTAN, but I suggest buying The LaTeX Companion (Frank Mittelbach and Michel Goossens, 2004, Addison-Wesley, Boston). It’s the definitive reference guide and contains a CD that has a complete LaTeX installation. The Not So Short Introduction to LaTeX2e (Tobias Oetiker, 2003) is a good starting point for learning how to create documents. Download it from www.ctan.org/tex-archive/info/lshort/english.

To convert documents between Microsoft Word and LaTeX, two tools from Chikrii Softlab (www.chikrii.com), Word2Tex and Tex2Word, might be useful to you. In the UK, purchase from Adept Scientific (www.adeptscience.co.uk). C

\documentclass{article} \begin{document} A \textbf{bold \textit{Hello \LaTeX}} to start! \end{document)

Mike Unwalla FISTC has been a technical writer in the software industry for over ten years. E: [email protected] W: www.techscribe.co.uk

A bold Hello LATEX to start!

FrameMaker 7.2: what’s the real deal?Bernard Aschwanden and Kay Ethier explore the latest version of this popular tool and the features associated with it.


�� Tools

IntroductionIn September 2005, Adobe released the latest version of its enterprise-class authoring and publishing software tool. We read the headline ‘Adobe Boosts XML Integration with Introduction of Adobe FrameMaker 7.2’ with high hopes. We saw high praise from John Brennan, senior vice president of Corporate Development at Adobe:

‘FrameMaker 7.2 delivers the features customers have been requesting most and extends Adobe’s market-leading integration of XML across its publishing and design product lines. FrameMaker software’s advanced capabilities enable forward-looking enterprises — in high-tech industries such as telecommunications, aerospace, semiconductors and information technology — to leverage the power of XML and produce compelling print, web and PDF content.’

Add to this features we really wanted and we were ready to dig in and try it out. You, on the other hand, may be wondering ‘What’s in it for me?’, and rightly so.

About ‘you’Maybe you are an information developer, working with structured or unstructured FrameMaker templates, and you want to find ways to make writing easier. You could be a manager, wondering if you need to update to the newest software. You could be an information architect, looking at ways to improve the documentation process. You may even be a software developer, looking for an easier way to share content with the writing team.

In any of these cases, there are arguments for and against upgrading to FrameMaker 7.2. In this article we examine the hype, the reality and the best approaches to plan for migration, if you decide to upgrade.

New featuresThere have been three releases in the 7.x family. Broadly speaking: 7.0 moved both the FrameMaker and the

FrameMaker+SGML products into one box, with one shared interface and added basic XML support. It also added several small changes to improve layout features, authoring and publishing to other formats.

7.1 upgraded several issues associated with XML output — including a fix for breaking of cross-references between XML files — but had very little to offer the user who didn’t have structured (XML) files.

7.2 features are explored in more detail in

this article, but generally can be summed into a few major items: improved import filters, multiple undo, improved structured (XML) authoring, updated templates and support files, DITA (Darwin Information Typing Architecture) support and XSLT (Extensible Stylesheet Language Transformation) pre- and post-processing.

Is this enough for you to update to 7.2? Let us explore and find out.

Import filtersIn each FrameMaker release, Adobe improves the import filters for graphics and for other text file types (like RTF). In version 7.2, there is a new version of the ITEDO import filter for CGM graphics designed to fix some of the graphics printing problems of earlier releases. There are also new import filters for PageMaker and QuarkXPress files, enabling FrameMaker users to convert from these formats.

Multiple undoThis was the item that got the most reaction when announced. Before we get into the details, let’s get grounded in why we need multiple undo.

Cynics would point out that FrameMaker is pretty stable, powerful and reliable. They would say that multiple undo has been missing for so long that authors are used to working without it. They might add that multiple undo exists in Microsoft Word because you need to try a dozen different ways to restart numbering, finally give up, and manually type the values. The cynics may be right.

Having used FrameMaker for as long as we have, it’s tough to say that multiple undo is worth the upgrade cost. It is a nice-to-have feature, but not a must-have. It does not perform nearly as well as the same feature in Word and there are many times that it can be a headache.

Undo is maintained using a History palette that is rather nice to see (but don’t bother using Help to search for History, since no topic is found). It enables you to see what the last change was. However, the number of actions that reset the Undo memory is painful.

Saving a file? Cannot be undone. Changing a cross-reference definition? Cannot be undone. Deleting an unused tag from the catalogs? Adding a new marker? Updating cross-references? Deleting a reference page? Guess what? The ‘cannot be undone’ message pops up about every five minutes when we build templates.

The good news in all of this is that you can select File > Preferences > General and tweak

‘You, on the other hand, may be wondering ‘What’s in it for me?’, and rightly so.’


��when to show warnings related to the history. This can save you from dozens of pop-up messages about undo during your working day!

Cynics would say that multiple undo is not the greatest implementation of technology. However, they should give Adobe credit for (finally) implementing it. The feature works well if you are an author, but could use more planning if you are a developer.

The final word is that the undo feature is quirky, but seems to be solid, generally reliable and has (on many occasions) made things easier for us as writers.

New templatesFrameMaker 7.2 sports new templates and a modified ‘Template Browser’, which is the thing that comes up when you select File > New > Document and click either Explore Standard Templates or Explore Structured Templates.

New to this version are structured versions of many of FrameMaker’s templates of reports, letters, memos, newsletters and outlines.

Users of the standard templates may notice fewer choices, since some of the templates (online and FAQ) are no longer listed in the Browser (though they are still in the Templates folder).

Updated structapps.fmWith the addition of new structured templates, the ‘structapps.fm’ file (which contains settings for FrameMaker’s installed Structured Applications) is augmented for the new templates listed previously.

A DITA structapps.fm is included as standard. Although relatively simple and not easy to use, it is a starting point for those who would like to experiment with creating DITA documents.

The first thing we tried was to take some sample DITA files and open them. Off to the DITA 1.1.2.1 sample files, where we found some map files. Open one in FrameMaker and… nothing. Open FrameMaker Help and search for DITA and… a message ‘No pages contain: dita’. Not to be defeated so easily, we turned to the concept files provided with the DITA sample files. Despite messages about fonts, table structure and attributes that had already been defined, the files did open. A few quick tweaks to the XML to let the system know that we wanted to use the DTD provided with FrameMaker and it opened more cleanly. It may not look pretty but DITA support is there.

The bad news is that you cannot count on the DITA tools provided to do the job right. The formatting is weak, the structure is wide open and the overall results require you to consider fixing the implementation before using it. The good news is that there are several third party companies that provide this type of service, and at least one or two that have working examples available to the public. Search the web for ‘dita’ and ‘framemaker’, and you should be off to a good start.

XLST pre- and post-processingThis item slips under the radar for most authors, but almost anyone who develops structured templates for importing or exporting XML needs it. It is probably the single best feature in FrameMaker 7.2.

Pre- and post-processing XML files enables transforms to be run to change code. If an XML file must be modified before it can be used with FrameMaker, you can do so. If the output needs to be tweaked beyond what FrameMaker’s read/write rules allow, it is possible.

Consider an example: we have a DITA template that outputs attributes for cross-references as srcfile regardless of what we try to get FrameMaker to do. By running a transform, we can tell the application to review the cross-reference and change srcfile into a proper href attribute on export. Then, when we import the same XML file, we instruct the application to first find the correct instances of href and make them back into srcfile, before FrameMaker even knows the error existed. Now we can rework XML files on export into a new document, without the need for a lot of FrameMaker development. Instead our XSL developers create a transform to build what we need for a given output.

As another example, consider a FrameMaker document ready to publish to the web. We can save the XML and have an XSLT automatically occur, so that the XSLT runs and our web output (perhaps XSLT) is ready and waiting for us.

Some issues that used to be resolvable only using read/write rules, or could not be resolved even with read/write rules, can be resolved by running XSLT. This could include major changes in the hierarchical structure of the elements upon saving XML.

The Xalan XSLT processor installs with FrameMaker 7.2 and is used for the transforms. If you are a Saxon user, the bad news is that you cannot change the tool that FrameMaker accesses for pre- and post-processing. However, you can ignore the pre- and post-processing and run the XSLT manually using Saxon. Though not ideal, it may save you from reworking existing transforms to work with Xalan.

Known issues

AcrobatThe extent of Acrobat issues is not fully known. Early feedback seems to show that FrameMaker works nicely with Acrobat 7.0.

Lost in translationNot the movie; and not the handling of double-byte characters and right-to-left text. There are things that we could do in version 7.1 but can no longer do in version 7.2. They may be minor, but we can’t help but wonder where they went.

In the past, Windows Explorer could be used to search for files with the .fm extension.

‘The final word is that the undo feature is quirky, but seems to be solid, generally reliable and has (on many occasions) made things easier for us as writers.’


�� Tools

These could then be dragged and dropped into FrameMaker book files as a quick way to insert files from numerous locations. No longer. Now you need to use the Add menu for every document that you need in a book. Are they located in six sub-folders? If so, select each folder and fileset and repeat the process. It’s annoying, but not enough to outweigh the benefits.

Remember double-clicking to open a file? If so, and you want the association to be version 7.2, uninstall version 7.1 first. The other option is to set your file associations so that .fm and .book files open with version 7.2 by opening Windows Explorer and selecting Tools > Folder Options (in Windows XP) and then selecting File Types and configuring as needed.

Using WebWorks Publisher? FrameMaker 7.2 ships with a new release of the Standard Edition.

Interface updatesExisting users will know that the interface has changed little since Adobe acquired the product from Frame Technologies. We still have a lot of issues associated with the look and feel: dialogs that do not resize properly, menus that jump the user from one location to another to work with structured features, palettes that are not easily configurable, icons that require programming skills to customise, and more.

The only really positive note is that there is a small Symbols button on the Formatting Bar that enables you to access frequently used special characters. Other characters can be added to this menu, but not as easily as you might wish.

Suggested solutionsSome of the biggest problems in FrameMaker can be resolved by using a couple of reasonably priced tools to fix them. However, before using any of these tools, bear in mind that they change the way FrameMaker works. That means you really need to test them before doing anything that could affect a real production environment.

Tired of dialogs in FrameMaker that don’t size the way they should? Change them using Resource Hacker (www.angusj.com/resourcehacker)

Looking to automate FrameMaker through the use of script-like actions? If so, consider either Mekon’s Frame AC (www.mekon.com/Technology/A-Z/FrameAC) or Frank Elmore’s FrameScript (www.finitematters.com). Both can create features similar to the macro utilities in tools like Word that make the author’s job simpler.

Need to manage conditional content within structured FrameMaker? Try Sourcerer from Advantica (www.advantica.biz/sourcerer).

Looking for better indexing tools? Explore the web and search for tools like IXGen (www.fsatools.com) or EmDex (www.emdex.ca). These provide a far more useful editor to work with when creating index entries.

Working with structured files and really want to fly? Get yourself a set of tools from West Street Consulting (www.weststreetconsulting.com): FrameSLT enables you to use features normally

only found in full XSL transforms in XML files. XRefWizard enables you to manage cross-

references more effectively. Structure Tools provide features that should

be standard for working with attributes and displaying configuration and shortcuts in context menus.

InsetPlus provides improved handling of text insets.

Wish you could track overrides or remove unused formats? You can do both with CUDSPAN plug-ins (www.telecable.es/personales/cud). All the plug-ins are free and come with documentation. They enhance productivity and are must-haves for any FrameMaker release.

Looking into DITA? If you plan to use DITA for your documentation, you may want to consider the FrameMaker and DITA template set from Publishing Smarter (www.publishingsmarter.com). The templates support a subset of the DITA standard and create content that is easily ported to other tools including XMLSpy and XmetaL.

There is also an online DITA and FrameMaker group worth exploring: http://groups.yahoo.com/group/framemaker-dita

By enhancing your toolset with free or inexpensive utilities, you will find that you can continue to be productive with both regular and structured FrameMaker.

ConclusionSo where does this leave you in your decision on upgrading? Well, if you have the budget to upgrade to version 7.2 and want to be current at all times, then you’ll upgrade no matter what we say. If you don’t have the budget and are not allowed to move to a new version, we can’t sway you either. However, for those of you wondering what to do, we offer this conclusion.

If you use FrameMaker and are totally content with how it works, don’t upgrade. However, if the multiple undo is worth the £165 price tag (and it may well be), then upgrade today.

If you work with structured files and you need the ability to output to XML, it may be worth upgrading (especially if you are using 7.0 at present with the broken cross-references ‘feature’). Add to that the ability to run transforms as you import and export content, and you leap ahead in productivity.

With some of the additional third party tools, we mention you may just be able to upgrade what you are doing even if you are still using release 6.0 from several years ago.

Just because it’s new doesn’t mean you have to buy it. Remember that, regardless of the decision you make, you still have one of the most powerful publishing tools at your fingertips. C

Bernard Aschwanden and Kay Ethier are Adobe Certified Experts and co-authors of Advanced FrameMaker from TIPS Publishing. E: bernard @publishingsmarter.com W: www.publishingsmarter.com E: kethier @travelthepath.com W: www. travelthepath.com

‘…regardless of the decision you make, you still have one of the most powerful publishing tools at your fingertips.’


�7

Taking FrameMaker a little furtherSteve Rickaby demonstrates FrameMaker’s supportfor long documents with repetitious layouts.

Tools

Jane Dards’ article in the Winter 2005 Communicator looked at how FrameMaker (FM) can create tables of contents and indexes. This article goes a little further, to show how FM’s indexing is powerful and flexible enough to support quite complex documents. It also looks at some other useful features, such as paragraph tag sequences, autonumbers, custom variables, and running headers, that can help when working with long documents with repeating layouts.

Constructing a directoryThe example used here is a directory of members of a professional body. The original was produced a few years ago as a regional directory of members of the Society for Editors and Proofreaders (SfEP), but the ideas behind the template can be applied to any document designed to list information that requires a repeating layout and multiple indexes. Examples include parts lists, business listings, recipes, or anything that needs to be made accessible in an organised fashion. FM’s long-document abilities really start to shine in such applications.

Setting up the layoutThe directory consists of a section that contains members’ details, laid out in a formal fashion, followed by several indexes. Each member’s entry consists of name, address and contact details, followed by paragraphs listing work skills, subject matter areas, media handled, qualifications, available equipment, recent clients and, finally, a free-text paragraph.

Figure 1 shows part of a page with fictitious

data. Several things are worth noting:The sequence of paragraphs for each

member’s entry is always the same.Some paragraphs are prefixed by a run-in

heading.Reversed headings are used to highlight the

start of each member’s entry.Specific keywords repeat throughout each

entry, particularly in the skills and subjects sections.

The page includes a running header that echoes the surnames of the members listed on the page.

FM provides features to help with all these layout aspects.

The members’ details section is followed by separate indexes that list members by skills, subjects, media, and geographical location. Figure 2 shows a section of the index by skill, created from the page shown in Figure 1.

More than one indexFM is not limited to one index. By default it provides the Index, Author and Subject marker types, which can all be used in indexes, but custom marker types can also be created. Why would one want to do this? As the default marker types imply, one application is to include separate indexes in a book for different topics, such as authors. The example here uses custom marker types for skill, location, and media, as well as the default Subject marker type, to give the required four indexes.

Creating a custom marker type is easy: choose Special>Marker to display the Marker dialog, then choose Edit… from the Marker Type pop-up menu. The Edit Custom Marker Type dialog allows custom marker types to be created, edited, or deleted. New marker types are then available at the book level when the indexes are set up.

In this application, each index lists only one

Figure 1. Part of a sample page from the directory of members

Figure 2. An extract from one of the indexes


�� Tools

marker type, as shown in Figure 3 for the index by skills. Indexes are added to the book using Add>Index Of>Markers from the book window.

Controlling the paragraph sequenceAlthough FM 7.x can be used in structured mode to exert rigid control over a document’s structure through an appropriate EDD (Element Definition Document), in many cases the time, expense, and complexity of creating an EDD is not justified.

The application described here uses a much simpler approach. Each paragraph shown in Figure 1 has a unique paragraph tag: Individual (Peters, Pritchard), Christian (Alison, Steve), Registration (Registered proofreader, Registered copy-editor), Address, Telephone, Skill, Subjects, Media, Qualifications, Equipment, Clients, Freetext. The Next Pgf Tag field in the basic properties of the paragraph designer is set up to sequence these tags. If a paragraph tag Telephone, for example, has Skill as its next tag, FM applies the Skill tag to the paragraph created when Return is pressed at the end of a Telephone paragraph. This provides a simple and quick means of controlling the formatting of information as it is entered.

Setting up the run-in headingsFigure 1 shows that the Subjects, Media, Qualifications, Equipment and Clients paragraphs have their titles set as run-in headings. FM

explicitly supports run-in paragraphs, but in this case the simplest way to create these headings is to define them as autonumbers in the paragraph tag definition. As previous articles in this series pointed out, autonumbers don’t have to be numbers. Figure 4 shows the autonumber definition for the Subjects paragraph tag. The Character Format field applies an existing character tag Bold to the heading.

In combination with FM’s ‘next paragraph’ feature, this means that each member’s section can be laid out almost completely just by pressing the Return key repeatedly.

Creating the reversed headingsThe reversed headings shown in Figure 1 are one-cell tables. FM offers a wide selection of table formatting controls: in this case the tables are set with no borders and a 70% black fill. This adds a little extra work to the layout, because insertion of the tables cannot be achieved using the ‘next paragraph tag’ method described above. As all heading tables are identical, however, they can simply be copied and pasted. (Third-party plug-ins are also available that make the insertion of ‘boilerplate’ layout objects very quick and easy.)

An alternative way of achieving a similar effect without using tables is to include a named graphic from the reference pages and position it behind the text. This wasn’t done here, though: it’s fiddly, and counts as a ‘hack’ but, more importantly, three separate paragraph types are used in each heading table, for surname (Individual), Christian name (Christian) and registration, as explained later.

The text of the three paragraph tags that occupy the heading tables is set in white, using the Color field in the Default Font pane of the paragraph designer, to achieve the reversed effect. The heading tables are anchored in a 2-point paragraph whose Next Pgf Tag is Address, so that pressing Return in the paragraph containing the table anchor creates a new address paragraph below the table.

Setting up the index entriesEach member is listed by skills, subjects, media and location in the indexes. A lot of index markers therefore have to be entered: a marker of the correct type is required for every entry in the address, skill, subject and media paragraphs of each member. Each must contain the key term as the first-level index entry and the member’s name as the second-level entry, separated by a colon. So the copy-editing skill entry for ‘Alison Peters’ contains ‘Copyediting:Peters, Alison’.

Anything that reduces the work involved in entering these markers is going to help. To make the process as simple and repeatable as possible, the relevant key terms can be set up as custom variables. Figure 5 shows the Variables dialog. Defining a variable called, for example,

Figure 3. Setting up a custom index

Figure 4. Using autonumbers to create run-in titles


��

Proofreading that contains only the word ‘Proofreading’ might seem on the face of it a rather strange and pointless thing to do. However, it gives several advantages in relation to indexing:Defining key terms as variables in an FM

template ensures that they appear identically every time they are used. This means that the indexes won’t end up with one set of entries for, say, ‘Copy-editing’, and another for ‘Copyediting’.

FM enters a word in the Marker dialog when it is double-clicked in the body of the document. If the word is a variable, however, FM places it in the Marker dialog with only one click: a click saved.

Double-clicking on a word in a document to place it in the Marker dialog only works for single words. Triple-clicking in FM selects a whole paragraph. If some key terms contain multiple words, such as ‘Consultancy (editing)’ or ‘Travel/Exploration’, defining them as custom variables allows the whole of the key term to be entered into the Marker dialog with only one click.

As the second-level marker information is the member’s name for all markers within a member’s entry, a sequence such as ‘:Peters, Alison’ can be stored on the clipboard and pasted repeatedly into the Marker dialog as the markers for each member’s information is entered.

Unfortunately, once the index terms are inserted in markers, they are no longer variables, just text, and won’t respond to changes in their original variable’s definition. FM does allow specific marker text to be searched for, however.

Whenever dealing with repeating terms, phrases or text in an FM application, it’s always worth considering using custom variables to contain them, and keyboard shortcuts make them fast to enter, too.

Setting up the running headersFM has a set of special header/footer variables that can only be used on master pages. There are four of these in FrameMaker 6, Running H/F 1–4,

and twelve in FrameMaker 7.x. These variables allow running headers and footers to reference other objects, such as the contents of heading paragraphs or chapter titles.

For example, if a document uses the paragraph tags Heading1 and Heading2 for the top two levels of heading, defining a running H/F variable as <$paratext[Heading1,Heading2]> will display the contents of the most recent level 1 or level 2 heading.

The page headers in Figure 1 show the first and last member’s names listed on each page. To create such ‘dictionary-style’ headers, the first two running header/footer variables are defined as <$paratext[Individual]> and <$paratext [+,Individual]>. The first variable definition picks up the text of the first instance on the page of the paragraph tag Individual, while <$paratext[+,Individual]> tells FM to use the text of the last instance of the Individual tag it finds on the page. The same technique is used to produce subject headers in the indexes.

It might now be obvious why the member’s headings are set up with multiple paragraphs for each member, one for their surname (the Individual tag) and one for their Christian name (the Christian tag): the surname needs to be available for use in the running headers. To keep all this information on the same line, the Individual tag must be defined as a run-in paragraph in the Pagination pane of the paragraph designer. This ensures that FM does not create a linefeed at the end of an Individual paragraph, so that the Christian paragraph can run on in the same line. The same method is used to allow the Registration paragraph to run on after the member’s Christian name.

The Default Punctuation field in the Pagination pane tells FM to insert characters automatically at the end of a run-in paragraph. Here we want a comma–space sequence after a member’s surname. FM helpfully excludes this default punctuation from a running H/F variable’s $paratext[paratag] definition. Alternatively, the comma–space sequence could be defined as the autonumber of the Christian tag’s definition: this approach is used to create the white space before the registration details.

Why not just type the required punctuation? Defining it in the template enforces uniformity, but also, if the punctuation were part of the paragraph’s text, the running headers would look like this: Peters, –Pritchard,… which is definitely not what is required. C

For more informationAll the FM features described in this article are covered in the FrameMaker User Guide and online help. The FrameUsers site and mail list are also very useful resources: www.frameusers.com.

Steve Rickaby BSc MISTC has been a freelance technical author and editor for 15 years, and has used FrameMaker for most of that time. E: srickaby @wordmongers.com W: www.wordmongers.com

Figure 5. Using variables to control invariant text


�0 Affiliate news

Following a period of gestation lasting over a year, during which there was extensive consultation with a small group of technical writers, the new MA in Technical Communication offered by the University of Portsmouth was validated in March 2005. The first intake of students is expected in October 2006.

The new degree scheme distinguishes itself from existing courses in a number of ways. Firstly, it is the only postgraduate degree programme in technical communication available in the southern region of the UK. Secondly, it is classroom-based, and offered in both full-time and part-time mode over a period of one or two years respectively. Thirdly, it has a number of attractive design features.

The degree is a joint venture between the School of Languages and Area Studies (SLAS) of the Faculty of Humanities and the Department of Creative Technologies (DCT) of the Faculty of Technology. The departments each contribute two core modules:SLAS provides the content modules,

Technical Discourse: theory and practice and Communicating with Different Audiences.

DCT provides the delivery modules, Electronic Publishing and Multimedia Communication.

It is envisaged that other modules or part-modules will be delivered by professional technical writers with teaching experience, and by academics from other departments or schools within the university with technical communication expertise.

A key feature of the programme is the project module, which is based on a technical communication project negotiated with a local or regional company. This replaces a dissertation and serves to underline the vocational orientation of the degree scheme. Students are prepared for the project, both practically and analytically, by the Managing the Project module offered in the preceding semester.

The depth achieved through engage-ment in the project is complemented by a range of technical communication tasks in the Writing to Inform and Writing to Persuade modules. This enables students to familiarise themselves with technical communication applications across a range of sectors, from the software, engineering and electronics

industries on the one hand, to banking, financial services and the public sector on the other.

Modules will be delivered jointly by professionals from, for example, the local IBM UK headquarters and Lockheed Martin, and by academics from the Department of Human Resource and Marketing Management, among others.

A further opportunity for the involvement of professional technical communicators in the degree programme is afforded by the Professional Aspects of Technical Communication module, which aims to maximise the opportunities for students to meet a variety of professional technical writers and representatives of the professional bodies and thereby learn about the profession as it is currently practised.

The programme also caters for the bilingual student through the Technical Translation module. Already there are early discussions on the development of a programme in Technical Communication and Translation.

The course has primarily been designed as a conversion programme to prepare students from a variety of backgrounds for entry into the profession. Applications are welcome from potential students with either a humanities or business background, or a scientific or technical one. Applications from individuals wishing to enter the profession as a second career are particularly welcome. Professional tech-nical communicators wishing to enhance their professional qualifications are also catered for through the flexibility offered by work-based learning schemes.

Opportunities for collaboration between academia and the profession were aired at a meeting with technical communicators in Portsmouth in December 2005, and the University is keen to offer itself as a venue for meetings of technical communicators in the southern region in the future.

To promote the programme, taster days have been organised for March and May 2006, again with support from professional technical communicators If you would like to attend the day in May, contact the Programme Coordinator, Ian Kemble, at [email protected]. For more information about the programme, visit www.port.ac.uk/MATechComm.

Cherryleaf offers a Technical Author Apprentice ProgrammeEach year, organisations hire graduates for roles in technical authoring, courseware development, information development and user-centred design. Since there are not very many academic-level courses in technical authoring in the UK, very few people entering the profession have any formal training or prior awareness of the role.

Cherryleaf’s Technical Author Apprentice Programme (TAAP) is a service that means you can hire people with technical competence and minimal work experience, and train them to be effective technical communicators.

TAAP offers training, management and mentoring to technical authors and information designers for their first year in your company. TAAP’s recruitment service can also find you people looking to start a career in this field and who would be suitable for this programme.

TAAP offers practical experience and researched theory. You can draw on Cherryleaf’s skills in teaching part of the BA Multimedia and Communication Design course at the University of

MA in Technical Communication

TechnicalCommunicationManagement

TechnicalCommunicationManagement

Oct. 1--4, 2006Kauai, Hawaiiwww.lavacon.org

The Fourth AnnualConference onThe Fourth AnnualConference on

LavaC n


�1Industry news

Coventry, developing corporate training courses in technical writing and technologies and Cherryleaf’s experience of running many documentation projects for clients.

TAAP is ideal for graduates who want to start a career in technical authoring. The programme is open to non-graduates as well. Contact Cherryleaf for more details at [email protected].

APT wins contract for large UK government conferenceAPT was awarded the contract for the design and localisation of material for the Department for Work and Pensions Round Table Conference on Poverty and Social Inclusion held in October 2005. The conference was attended by David Blunkett, along with hundreds of delegates from around the world, and was a flagship event highlighting the UK’s presidency of the EU.

APT designed, translated and printed the official conference guide, as well as providing six conference reporters to produce summaries of the workshops that took place over two days at the Moat House Hotel in Glasgow.

Ablewisp starts producing podcastsNew ISTC Business Affiliate, Ablewisp, has started preparing podcasts. The first, CE marking in 17 minutes, is a detailed overview of CE Marking for designers and manufacturers based in the EU. It is available from the download link on www.ablewisp.com.

Ablewisp MD Stuart Miller (below) says the company has ideas for future podcasts on CE marking for importers and Approvals and guarantees of safety. ‘We also hope to produce

podcasts covering subjects on technical documents,’ he adds.

Ablewisp designs and writes all types of technical documentation and provides compliance-engineering services, including training in CE marking.

Lionbridge plans to double Logoport usage this yearProvider of globalisation and off-shoring services, Lionbridge Technologies, will continue its deployment of its web-based language management technology Logoport, and sees the potential for more than doubling its usage during 2006. During the first half of 2006, the company also plans to release a new and comprehensive linguistic-management platform using the Logoport suite of language asset tools, including customer-specific integration of machine translation.

This follows the company’s announcement that Logoport has managed more than 110 million words since its initial deployment in early 2005. Within one instance of code, the Logoport system currently supports more than 4800 users worldwide, encompassing Lionbridge staff, in-country translators and clients. The company is using the technology for more than 70 clients, supporting its hosted, on-demand, managed service model. Lionbridge achieved these figures in less than 10 months.

The Logoport technology is offered as a free service to Lionbridge clients and translators, and is fully compatible with all industry-standard language tools. Engaged through a simple plug-in tool, Logoport’s on-demand architecture enables the simultaneous use of multiple translation memories within each client and facilitates real-time collaboration among all project participants. With no globalisation software to purchase, download or maintain, newly translated content is immediately available to all translators through the web, improving turn-around time, consistency and quality. Logoport’s advanced security features ensure confidentiality and protect each client’s proprietary content, while offering full back up and recovery with full scalability.

Written by Kathryn Valdal Fourie. If you have a story for the news pages contact us at [email protected]

WordPerfect Office X3 releasedWith better interoperability with PDF files, Corel claims that its introduction of WordPerfect Office X3 represents a threat to Microsoft Office. Users can now convert PDF documents into WordPerfect, making it the first and only office suite to import and export documents (and export spreadsheets and presentations) to PDF, one of the most widely deployed open formats.

Providing enhanced compatibility with Microsoft Office, as well as industry-leading feature richness, ease-of-use and value, WordPerfect Office X3 sets a new standard for content reuse in word processing. In addition to PDF Import, it offers a wide variety of new and enhanced features, including a new e-mail client, a fresh new user interface, new online resources, enhanced multilingual character support and the powerful ability to easily eliminate hidden metadata. These new capabilities are complemented by classic features such as RealTime Preview, context-sensitive toolbars and task-oriented wizards.

There are standard and home editions. For information on upgrading from Microsoft Office to Corel, go to www.wordperfect.com.

Prestigious award win for lymphatic cancer charityThe Lymphoma Association, the only specialist UK charity that provides support and information to lymphatic cancer patients, won a prestigious award for the quality of one of its publications in November 2005.

The BMA Patient Information Award for Printed Materials, was set up in 1997 to encourage excellence in the standard of patient information. This year, 223 booklets were entered,

Stuart Miller


�2 Industry news

with the Lymphoma Association’s Lymphomas taking the first prize.

Aimed at people affected by both Hodgkin and non-Hodgkin lymphoma, the 87-page booklet was described by its reviewer as ‘the best single source of information on lymphomas written for the public that I have ever come across’.

Every year, nearly 11 000 new cases of lymphoma are identified in the UK alone, making it the seventh most common cancer and the most common cancer affecting people under 30.

Rush to register your .eu domain nameAs of 7 April, anyone can register an .eu domain name, without supporting claims with documented evidence such as registered trademarks. The European Registry of Internet Domain Names (EURid at www.eurid.eu) is calling this the Land Rush period.

From 7 December 2005 until 7 April 2006, known as the Sunrise period, domain names were only available to holders of prior rights. Applicants had to support claims with documentary evidence. EURid explains that it put this phased registration into place to enable organisations and companies to protect their domain names against abusive registration by cyber squatters.

When EURid opened its systems to receive applications for .eu domain names, some 800 registrars in 25 countries began sending in the

applications that they had received from numerous candidates all across the EU. The highest percentage of applications originated from Germany. The Netherlands and France were the second and third greatest source of applications, with the UK coming fourth.

More top intranets come from Europe Internet guru Jakob Nielsen’s annual report on the best intranets of 2006 reports that, for the first time, most winners are not US companies. There were two winners from the UK, one from Ireland, one from Germany and one from Australia. Nielsen says that this result highlights the continued growth of good intranet design around the world. The ten best-designed intranets for 2006 are:Allianz Australia Insurance, AustraliaALTANA Pharma AG, GermanyBank of Ireland Group, IrelandCapital One, USAIBM, USAMerrill Lynch, USAMETRO Group, GermanyO2, UKStaples, USAVodafone, UK.Nielsen explains that ‘the globalisation of good intranet design is actually greater than this simple list implies; many of the winning companies are highly multinational, with team members operating in multiple coun-tries. At Vodafone, for example, intranet technology is managed from Germany, with development efforts occurring in California, Spain, Italy and Egypt.’

Adobe Lightroom Beta 1 now availableYou can download Adobe Lightroom Beta 1 until the end of June. This is a public beta, not a final release, so Adobe explains that neither the quality nor the features are complete yet.

Adobe says that Lightroom is a new way for professional photographers to import, select, develop and showcase large volumes of digital images. The aim is to enable you to spend less time sorting and refining photographs and more time shooting them. Its clean, elegant interface steps out of the way and lets you quickly view and work with the images you have taken today, as well as the thousands of images that you will shoot over the course of your career. As no two photographers work in the same way, Adobe Lightroom adapts to the workflow rather than forcing the workflow to adapt to the tool.

You can view and compare photographs quickly and easily. Precise, photography-specific adjustments enable you to fine-tune images while maintaining the highest level of quality from capture through to output. Lightroom will run on most commonly used computers, even notebooks used on location. Initially available as a beta for Macintosh, it will later have support for Windows.

To download Lightroom Beta 1, visit http://labs.macromedia.com/technologies/lightroom.

Publication of the 2005 Inttranews ReviewThe 2005 Inttranews Review, a status report on the language industry worldwide in 2005 and forecasts for 2006, is now available on-line at www.inttranews.net.

During the first full year of operation, Inttranews has read and reprinted excerpts from some 5400 articles on interpreters, translators and linguists published in over 60 countries. That provides a unique overview of the events and issues that have mattered this year in the increasing number of fields in which the language industry is involved. More importantly, this indicates what may matter in the months to come.

PASS Engineering appoints Net-Translators as Middle East resellerProvider of translation and localisation services, Net-Translators, and software localisation company, PASS Engineering, have joined forces to deliver integrated localisation solutions to the Middle East.

PASS Engineering explains that the PASSOLO/Net-Translators alliance addresses a number of issues and challenges in the Middle Eastern marketplace, such as the convergence of development and translation departments and the resulting demand for more integrated solutions, but also the increasing use of advanced development technologies such as .NET and Borland Delphi.

PASS Engineering also has partnerships with Sinometrics for North America, Skrivanek for Central an Eastern Europe, and Euro-Far East for the Asian marketplace.

Best international deployment award for CNHA leader in the emerging market for global information management (GIM) solutions, SDL International has

Catriona Gilmour Hamilton (left), Special Projects Manager at The Lymphoma Association and author of the Lymphomas booklet, accepts the award from Professor Dame Barbara Clayton, Honorary Research Professor in Metabolism at the University of Southampton.


��announced that CNH’s ASIST system for providing web-based support to over 6000 dealers worldwide was awarded Knova Software’s ‘Best International Deployment’. The SDL Knowledge-based Translation System (SDL KbT System) integrates with Knova Software’s Service Resolution Management application to localise support knowledge quickly and cost-effectively so that dealers worldwide are able to find resolutions to customers’ concerns 24 hours a day, seven days a week.

SDL KbT System, a powerful combination of translation automation technology and quality human translation services, provides rapid turnaround of high-quality translations at significantly lower cost than traditional translation. Its performance has enabled CNH to translate more support knowledge objects more quickly, helping to drive self-service levels up to over 80% and increase dealer satisfaction.

Applied Language Solutions wins ATL Enterprise AwardUK-based translation agency, Applied Language Solutions has been presented with an award by ATL Enterprise (www.atlenterprise.co.uk). The award, sponsored by KPMG, is given to independently owned businesses formed within the last three years. Applied Language Solutions has grown rapidly since it was founded by Managing Director Gavin Wheeldon in late 2003. The translation agency had to demonstrate why its service stands out from the crowd and how its philosophy drives the business forward.

‘We provide translation services for all types of electronic media and paper documents. The area in which we excel is providing translation of more complicated file formats, websites and design files to very short deadlines.

‘We have an excellent in-house programming team, which has developed what I believe to be the best Project and Sales Management system in the translation industry. We are now developing additional value for our customers and suppliers, such as a portal for interaction with our systems and an interface to our internal system for integration from customers’ own systems, such as CMS or eProcurement.’

Applied Language Solutions has achieved ISO 9001 accreditation and is working towards Investors in People.

The Yorkshire Enterprise and Diversity Convention 2005 showcased the excellent work being carried out by ATL and its partners in recognising and celebrating the achievements of a diverse business sector in Yorkshire. The awards were sponsored by York-shire Forward, Business Link for West Yorkshire, UKTI, Barclays and KPMG.

New name for Ycomm EuropeYcomm Europe, a daughter company of Japanese printing group Yamagata Corporation, proudly announces its new name, Yamagata Europe. The change of name, which brings various sister companies in Europe, South-East Asia, China and the US under a single banner, corresponds, not coincidentally, with the hundredth anniversary of the Japanese mother company.

Ycomm Europe was established in 1998 by Geert Benoit. During the past four years, the company has undergone tremendous expansion during which the number of employees has risen from four to 22. Yamagata Europe has grown to become a professional and mature player in the European documentation market that offers its clients from various sectors integrated solutions to their printing and translation needs.

You can visit the new website at www.yamagata-europe.com

ProposalGENie launches recruitment driveProposalGENie is on the expansion trail, having recruited eight distributors to sell its product in the UK. This is the result of growing demand for ProposalGENie’s web-based system, which automates the production of sales proposals and enables salespeople of varying abilities to produce proposals of consistently high quality.

The system is now being adopted by companies all over the UK in different sectors including accountancy, telecoms, retail and property.

New division for delegate documentsIndexing Specialists (UK), based in East Sussex, has announced a new division for preparing conference documents. It will prepare timetables, proceedings, advance papers and abstracts from start to finish, using its extensive indexing and proofreading skills.

With over 40 years’ experience, Indexing Specialists prepares indexes for a wide range of printed material from books to reports. It employs special-ists in many areas, including art, law, finance, social science, environmental science, chemistry, physics, biology, medicine and engineering.

Most recently, the company provided timetables, edited abstracts, and subject and author indexes for a major scientific conference held at the University of Warwick. The event was attended by over 800 delegates from many research centres within the UK.

MD Richard Raper said that, following the successful completion of this project, he decided to set up a dedicated conference document division. The indexing expertise that the company has developed in many areas will enable it to grow successfully in this new sector.

Written by Kathryn Valdal Fourie. If you have a story for the news pages contact us at [email protected]

The Applied Language Solutions team

The finishing touchBill Johncocks launches his regular indexing page by explaining how a good index makes a manual fully usable.


�� Indexing

Manning an IT helpdesk can be pretty soul-destroying and a really clueless caller can provoke the staff to intone ‘RTFM’, an acronym where three of the letters stand for Read The Manual. It seems nobody can win in a helpdesk interaction, because every contact grows out of an initial failure. Certainly users who psyche themselves up to make a long and humiliating call must first have felt at least equal frustration. They know the solution is at their fingertips; they just can’t find it using the index, and that’s because user manuals have some of the most unusable indexes in the world.

Why is this? After all, most manuals are painstakingly compiled by intelligent, dedicated professional communicators — people just like you and people, presumably, not too unlike professional indexers. So why are so many of their indexes dire? I think the answer is simple: most technical communicators still omit the first, crucial stage of constructing a usable index, which is to imagine yourself in the reader’s shoes.

Thinking like your readersA book index may serve two readerships: those who have read the book and are looking for something they recall seeing, and those who haven’t, but want to find a relevant section (and, where that section addresses an urgent problem, as in a book on dealing with household emergencies, the index must be efficient). We know nobody wants to read an entire manual — they’d even rather call a helpdesk — so the second role must be important for manuals too, but their indexes often address just the first, assuming a familiarity with specialised vocabulary that the first-time reader can’t possibly have attained. Precise and consistent wording is a virtue in section headings and captions but trans-ferring these terms without thought can produce a completely unusable index.

Most manuals start by naming compo-nents, then go on to describe how things work. Often though, readers won’t know those names or want that explanation: their approach is use-centred, arising from a real-world need, and they expect to be guided quickly to its solution. They

might look for ‘Punctures’ not for ‘Wheel changing’, say, or for ‘Starting’ not for ‘Ignition subsystem’.

Full-time indexers try to approach documents from the likely reader’s viewpoint, whereas even authors with good indexing skills can grow so used to their chosen terminology that they risk being trapped within it. Full-time technical writers, retained to document a specific project, presumably start out with a detached view too, but may quickly find themselves becoming ‘institutionalised’.

Special problems with consumer guidesParadoxically, it’s not the most technical material that causes the worst problems: it’s in indexes to consumer product guides where the disparity in knowledge and vocabulary yawns widest. The author of a textbook on semiconductor theory will write at a level suiting its intended readership: the author-indexer of a short user guide for a digital camera actually has a harder job and one needing more imagination. After living with the product and becoming steeped in its jargon, he or she may already speak a quite different language from its purchasers.

Worse, manual authors sometimes have to aim at a moving target. Because good technical writing educates and informs, a reader who starts out knowing no more than that the product is recommended by the guy down at the pub or by Which? magazine should, after a few pages, be familiar with the control layout, the meaning of any error messages or warning lights and the names of key components and operations. This calls for real subtlety in separating low-level information from the more advanced, and indexing both appropriately, although a well-designed manual’s structure should reflect this progressive acquisition of expertise and so provide clues.

Usability testingA good book index might just swing purchasing choices in bookshops but manuals aren’t often available before purchase so, where user documentation is concerned, customers have to buy a pig in a poke. But get it right and (assuming

the product also does its job) customer satisfaction and brand loyalty should be guaranteed. Really good technical indexing is a rare skill but an author who recognises indexing as a separate problem has already taken the key step.

Might drafting an outline of each new project in users’ language, before you immerse yourself in the specialised vocabulary needed for its documentation, be time well spent? And, on completion, don’t just get your work approved by the in-house development and marketing teams: why not test it on colleagues uninvolved with the project or (if commercial confidentiality allows) on friends or relatives with similar backgrounds to the intended users? If your in-laws find your instructions for connecting up a new DVD player hard to follow, they probably won’t be alone. Nor will they if they look in the index for terms you didn’t expect. Those they do look for might be good candidates for index entries.

Getting helpWhether you index technical publications yourself or find a specialist through the Society of Indexers, do take it seriously. Most of us only read enough of a manual for our immediate needs, then return to it when we meet new challenges, so nothing you write should be read more than once. If it was understood the first time, it has done its job but, if your readers have to scan pages again, looking for things they can’t find in the index, you’ve failed as a communicator no matter how clear your text and diagrams.

And, while a rare skill, indexing needn’t be a big chore: training is available through the Society, common sense is fully applicable and future articles on this page should help you produce indexes that take readers straight to solutions, without needing to make any telephone calls. C

Bill Johncocks is a freelance Accredited Indexer living on the Isle of Skye, who specialises in embedded indexing of technical documents. E: [email protected] W: www.technicalindexing.com Society of Indexers: www.indexers.org


��

What does a copyeditor do?As a prelude to our new editing page, the SfEP explains first the role of copyeditor and, in the next issue, of proofreader.

Editing

Contrary to popular opinion, copyediting is not just about dotting the ‘i’s and crossing the ‘t’s. The copyeditor’s role is to help the reader grasp the author’s ideas, to prevent embarrassing errors and to ensure that the typesetter can do a good job. Among other things, professional copyeditors will:Correct errors in spelling, grammar,

punctuation, style and usageEliminate inconsistencies and

repetitionApply house style (as necessary)Clarify ambiguities and inaccuracies

with the authorEnsure that the text is structured

logically and coherentlyMark up hard copy with conventional

symbols or edit files on-screen using word-processor styles or tags if required

Organise illustrations and ensure that labels and legends are consistent with the text

Have the technical knowledge needed to communicate with the designer and typesetter, to minimise costs and maintain schedules

Identify legal issues relating to copyright, libel, obscenity, blasphemy or incitement to racial hatred (although responsibility for them lies with the author).

Why do I need a copyeditor?Perhaps, as an author, you know what you want to say but find it hard to put into words. Your very closeness to and familiarity with your work may be blinding you to its flaws and inconsistencies. A copyeditor will be sufficiently detached from the writing process to spot mistakes and ambiguities that might distract the reader. He or she can add a professional finish to your work that puts it a cut above the rest.

Can I do it myself?Many authors might question whether they need to employ the services of a professional copyeditor, arguing that they could do the job themselves. For the reasons given above, the answer is usually ‘yes, you do need a copyeditor’.

However, if you do decide to do the work yourself, here are some basic guidelines:Know your audience

Check that you have pitched your language at the right level.

Extent Is it too long/short?

Content and structure Is anything missing or redundant? Is the order logical? Are tables and items of artwork adjacent to their points of reference in the text?

Sentence and paragraph length Again, bear in mind the readership but, in general, keep sentences short and use paragraphs to introduce new ideas and break up the page.

Consistency Keep a list of your decisions about alternative spellings and hyphenation, for reference at proof stage.

Illustrations and tables Make sure that your illustrations support the text and have an appropriate legend.

Style Common mistakes include the overuse of emphasis (in italic, bold or capitals); very long sentences with little punctuation; changing between first and third person.

Accuracy Double-check facts and spellings of names, dates and quotes, even if you think you know them.

Copyright Permission must be sought from the copyright holder (the publisher and/or the author) for illustrations and tables taken from other sources.

Engaging a professional copyeditorSome of the skills to look for in a professional copyeditor include:Training in editing (such as courses

run by the Society for Editors and Proofreaders or the Publishing Training Centre)

Editing experienceSpecialist knowledgeCommunication skillsKnowledge of EnglishGood judgement — the ability to

assess when to be flexible in applying house style

Restraint — in not rewriting in their own style; willingness to ‘let the author’s voice come through’

Ability to stick to deadlines and budgets.

You can discuss the work initially by phone or in person. If so, follow up by e-mail or letter right away with what you’ve agreed. When you send the job to the editor, include the following information:Lists of enclosures and outstanding

material — itemise what you are supplying and what is yet to come.

Tasks to be performed — give guidance about the depth of editing. Is the editor required to prepare preliminary pages, running headings, cover copy and so on?

Important features and relevant background — who is the target audience? Is the book in a series? Is there a house style or design specification?

Administrative requirements — is the editor required to produce handover notes for the artist, designer, production or typesetter? Are there any instructions for presentation and listing of illustrations?

Delivery requirements — state the agreed dates, fee, expenses and payment period. C

ResourcesBS 5261C:2005 Copy preparation and proof correction. Marks for copy preparation and proof correction (extracted from BS 5261-2:2005).

SfEP Code of Practice www.sfep.org.uk/pages/sfepcop.asp

SfEP Directory of Editorial Services www.sfep.org.uk/pages/directory.asp

For further details on copyediting, contact the office of the Society for Editors and Proofreaders. T: 020 7736 3278 E: [email protected] W: www.sfep.org.uk


Professional guides for technical communicatorsQuality control for technical documentation by Andrew MarlowPublisher: Marlow Durndell (www.marlowdurndell.co.uk), ISBN: 1-873407-09-2, 47 pages. Paperback 2005, £10Reviewed by Iain Wright FISTC

�� Book review

The stated aim of this book is to foster the idea that quality management should be an integral part of every technical documentation project.

To that extent it succeeds. The author demonstrates his extensive knowledge by considering different viewpoints on quality — something that, being subjective, is notoriously hard to define. The difficulty of this subject is compounded further by the variety and diversity of items and processes that require technical documentation, and the media used to carry them.

The overall structure of this book is sound, commencing with why quality is important, then going on to look at possible approaches, strategies for quality control, reviews and quality assessment.

Chapter 1 explains the importance of quality and how good documentation benefits the product, pleasing the user. The book focuses on how poor documentation might result in liability, but misses the point that missing docu-mentation might be a worse offence.

Chapter 2 provides an overview of approaches to quality management systems, without giving a preference.

Chapter 3, on defining strategy, is more instructional and quite useful. It looks at roles and elements in designing documentation (excluding the physical

production for the chosen medium).Chapter 4 covers the many types

of review reasonably well. Control of paper documents and their mark-ups is described. However, now that many documents are prepared electronically, the book’s advice for online reviews would be improved by the inclusion of general tips, for example, locking review documents for annotation only.

If quality is difficult to define, its assessment is truly tricky to achieve. Nevertheless, the author offers handy top-level advice on methods and tools for doing this. However, that leads me to one of the things I find disappointing about this book. It is, for me, too top-level. I would like to see more tips, advice and examples. I feel that something is missing. Wearing my ‘quality manager’ hat, I notice that the book refers to a companion guide, Project Management for Technical Documentation. While I have not read this book, the separation of quality from the project implies that quality is not an essential component.

To a certain extent, the book does what it says it will do, but I wanted more. Its struggle with the fact that quality is subjective, meaning different things to different people, results in it being descriptive rather than instructional. It is not a document for step-by-step

instructions on quality control — you have to read complete chapters rather than jump in — but it does highlight elements that you should research and apply to technical documentation. C

Book review manager’s postscriptI reviewed the companion guide, Project Management for Technical Documentation (ISTC Newsletter, December 2005). In that book, quality is discussed as an integral part of project management, for example, in planning, development of standards and reviews (during and after the project). The evidence in the series so far is that the presence of a separate book for a subject does not mean that relevant material is excluded from the companion guides. — Linda Robins.

Andrew Marlow MISTC has over 25 years’ business experience including 20 years in the IT industry, specialising in the field of technical communications. He holds numerous graduate and post-graduate qualifications in a wide range of subjects including science, computing, manufacturing and business administration. Book review managers: Linda Robins and Poornima Kirloskar-Saini E: [email protected]

QUALITY TRANSLATIONS INTO ITALIAN SINCE 1986• Technical translations: user manuals, product literature, catalogues and brochures• Corporate literature, patents, websites, financial, legal and promotional translations• Terminology and Translation Memory management with Trados and Star Transit• Desktop publishing (FrameMaker, Indesign, Quark Xpress, PageMaker etc.) on Windows and Mac platforms• Software localisation• International project management• Professional in-house proofreaders and project managers

One of the first translation centres in Italy to be awarded Quality System certification to ISO 9001:2000 and Italian standard UNI 10574.

A member of EUATC

interlanguage s.r.l. - Strada Scaglia Est, 134 - 41100 Modena, Italy - Tel. +39 059 344720 Fax +39 059 344300e-mail: [email protected] - www.interlanguage.it

C

M

Y

CM

MY

CY

CMY

K

Inserzione2.ai 15-02-2006 9:06:31


�7

Back to basicsThe ITEDO team continues its exploration of thebuilding blocks of technical illustration with the line.

Illustration

The line is the most basic element of a technical illustration. However, if you think that basic means simple, you are mistaken. The shape, thickness and significance of lines in an illustration all contribute to its artistic effect and its success in conveying form.

This overview, which can only scratch the surface, concentrates on the kinds of lines created in vector graphic tools, such as ITEDO’s IsoDraw and Adobe’s Illustrator. It is intended to help those who are not experienced illustrators to use lines more effectively.

Types of linesThere are various types of lines, as shown in Figure 1:A line is defined as a straight line

between two points that has a beginning and an end point.

A polyline is a line with several points. It has not only a start and an end point but other points in between that may not lie in a straight line. An example is a zig-zag line.

A Bézier curve (named after the French mathematician Pierre Bézier) is defined by mathematical formulas. The two endpoints are called anchor points. The other points, which define the shape of the curve, are called handles, tangent points or nodes. A handle can have one or two control points; moving these points modifies the shape and direction of the curve. As a result, a Bézier curve uses at least two anchor points and one handle to define a curve.

Most graphics programs offer a wide range of line drawing tools, but illustrators have to use them in an appropriate way to create an effective technical illustration.

Some recommendations follow on how to show lines in technical illustration and, of course, these ideas can also be applied to working with pen and ink.

Representational linesThe simplest form of a line-art representation is the oneline representation. This means that all lines in the illustration are of the same thickness. To convey form more

effectively, however, very often two or more line thicknesses are used, as shown in Figure 2. This stylistic device is called thick and thin technique. The actual and relative weights of the lines are determined by house style and aesthetic effect; a typical recommendation is for thick lines to be twice the weight of thin lines.

Thick lines tend to be applied to the outer edges of the depicted objects, while thin lines are used for inner edges. You might imagine reaching behind a line with your hand: if you would not able to see your fingertips, the line should be thick (Figure 3).

Lines may sometimes be broken and their thickness may change after the break, for example, to suggest a change from an outline to a contour. This is often the case with castings, as shown in Figure 2.

Thicker lines are sometimes used to highlight specific objects. Colour, if available, may be used in the same way or to convey more information about the depicted objects.

Additional linesWhen you have created your illustration, you might want to apply more lines to complete it. There are several types of lines with special functions, including:Leader lines for annotationsCentre lines in exploded views;

these are often dashed.Adding white shadows helps to distinguish leader and centre lines from the representational lines within the drawing itself.

ConclusionCareful selection of the lines that you show and the styles that you use will enhance the overall impression created by an illustration. Removing hidden lines, provided that they are not needed to convey details of concealed parts, can tighten the focus on important aspects of the depicted object. Everything you include, and by implication everything you omit, should be chosen to help the viewer to envisage the object more easily.

Further informationIf you would like to know more about the role of line thickness, there is an useful article by Conrad Taylor at www.ideography.co.uk/infodesign/eigvil/presentations/Linethicknesses.pdf. C

Bettina Giemsa is responsible for marketing at ITEDO Software in Germany, vendor of the technical illustration products IsoDraw and IsoDraw CADprocess. E: [email protected] W: www.itedo.com

Figure 3. Determining line weight

Figure 1. Types of lines

Figure 2. Use of thick and thin lines

Document processing for accessibilityRichard Hodgkinson reports on the development of European guidelines for publishing accessible documents.


�� International standards

I wrote in the Autumn 2003 Communicator about accessibility, describing the US Government’s requirements for documentation in the purchase of IT products and services. Both nationally and internationally, the needs of disabled members of society are increasingly being recognised and addressed by legislation, standards and guidelines.

What is CEN/ISSS WS DPA?As part of the European Commission’s activities to enable participation of all members of society in the knowledge-based economy (‘e-Inclusion’), the Information Society Standardisation System of the European Committee for Standardisation (CEN/ISSS) has established a workshop (WS) on document processing for accessibility (DPA) to develop guidelines to enable all published information to be more accessible to people with disabilities.

Given the widespread adoption of information and communication technology within the publishing industry, there is a general interest in the creation and provision of well-formatted digital documents. For those people who are dependent on accessible information, this interest is of central importance. It is this convergence of interests that offers exciting opportunities for these different stakeholders. The workshop is examining the ways in which this convergence is helping to build consensus and create new standards and technologies that enable the provision of information in formats that are more accessible for everyone.

Taking the broadest definition of content creators, the workshop aims to produce guidelines to help them provide accessible information. For example:How should a publisher structure PDF

documents to maximize accessibility?How can document processing chains

incorporate accessibility at an earlier stage to avoid prohibitive costs?

How does one provide structured audio for Talking Books?

How can content creators provide services for these new markets?

This work is now feasible due to recent developments at several levels. From a technical perspective, it is now possible to address key concerns of content creators and providers and coherently address issues such as automation of document structuring, adherence to emerging standards, workflow support, digital rights management and secure distribution platforms.

Similarly, emerging international and European standards provide an excellent basis for the creation of accessible information at a more fundamental level than has previously been possible. At a European and national level, there now exists a clear desire on the part of associations of publishers to collaborate closely with experts in order to provide truly accessible materials.

However, what is needed is a focal point to bring these disparate initiatives together. The workshop aims to provide this cohesion by addressing the key areas and issues, which are of common concern to everyone involved in this area. This is an ambitious goal, but the convergence described above makes this both worthwhile and achievable.

ObjectivesThe workshop has three key objectives:1. To bring together all the players

in the information provision and e-publishing chain to achieve the critical mass necessary to enhance significantly the provision of accessible information at a European level

2. To provide guidelines on integrating accessibility components within the document management and publishing process rather than as just a specialised, additional service

3. To raise awareness and stimulate the adoption at local, regional, national and European levels of the emerging formats and standards for the provision of accessible information, and to find ways of ensuring that technological protection measures do not inadvertently impede legitimate access to information by people with print impairments.

ParticipantsCurrent participants represent Adobe, the OASIS DITA Committee, IBM, RNIB, ISTC, the Federation of European Publishers, the UK, Netherlands and Danish National Libraries for the Blind, Dolphin Audio Publishing, national standards, disability organisations and universities from Austria, France, Germany, Greece, Ireland, Italy, the Netherlands, Poland, Spain and the USA.

EUAINSupported by the European Accessible Information Network project www.euain.org, this work is funded by the e-Inclusion thread of the European Commission and co-ordinated by FNB Netherlands. EUAIN aims to promote e-Inclusion as a core component in the establishment of the information society by creating a network to bring together the different players in the content creation and publishing industries around a common set of objectives relating to the provision of accessible information.

What happens next?The plan is to produce a set of guidelines in the form of a CEN/ISSS Workshop Agreement (CWA) that will be freely available from the CEN/ISSS website. The CWA is intended to form the basis of a future CEN standard. The workshop will hold several meetings and, later this year, a draft will be available for public comment. The CWA is planned for publication in 2007. C

Richard Hodgkinson FISTC has been involved in the development of ISO IT standards since 1990 and represents the UK on three international committees. He is Convenor of ISO/IEC JTC 1/SC 7/WG 2 and editor of several ISO IT standards on software documentation, icons and accessibility. E: [email protected]


��

Localisation, localisation, localisationMonica Basting explores how building good relations with a localisation company can make the process more effective.

Translation

Products and services need to appeal to local customers. Unless you are trying to sell a truly universal item, your offering will need to be geared to its target market, or ‘localised’. In this article, we focus specifically on the localisation of product or service communications, such as websites, brochures, direct mailers, in-store promotions and packaging.

What is localisation?Localisation is the cultural adaptation of a product or service and involves tailoring a product to its market in a process that goes beyond translation to include differences in such areas as legal restrictions, symbols, colour associations or payment preferences.

Which localisation company?To achieve the best results, you should work with a localisation company that has the expertise to meet your needs. But how will you know if there is the potential for a good fit?

First, be clear about what you need in terms of language range, sector knowledge, tone and copy style. Select only companies that have the relevant experience: a software localisation specialist is unlikely to be able to provide creative advertising copy for a consumer campaign.

Second, meet or telephone a sales representative to discuss your business. Do they ask detailed and intelligent questions or just promise the earth? And note how they answer your questions, which should include: What type of projects do you

specialise in? (If yours is a complex 40-language project for a children’s cartoon website and the company specialises in technical manuals, you should probably keep looking.)

Who will do the translations? (If their translators are in-house rather than in-country, think again.)

How do you manage projects?Are you ISO 9001 certified?Will we have a dedicated project

manager and can we monitor project status online?

What other services can you provide?Can you supply client references?

Would you be willing to do a test piece free? (Provided your request is reasonable — up to, say, 500 words in two language directions — this should be acceptable.)

How do you monitor quality and seek client feedback?

Effective client briefingOnce you have selected a localisation company, the onus is on you to provide a good brief, ideally including information from both columns of the table above. The better your brief, the better are your chances of receiving high-quality translations on time and within budget.

Understanding the process To get the best out of the company, you need realistic expectations of what it can achieve in a specific timeframe.

The first principle is that there is always a trade-off between time and quality. The tighter the deadline, the less time there is for the necessary processes of editing, revision and proofreading. A skilled translator can produce around 2000 words a day, while an editor (who reviews the translation against the client brief) can edit around 6000. It takes another day for the copy to be reviewed against the source text and proofread. A reasonable timeframe for the delivery of 8000 words is around seven working days, then, so demands for a 48-hour turnaround can be achieved only by compromising on quality and cutting corners.

Second, clients often don’t

understand the time and cost implications of making amendments once the project has started. To change just one word in English may involve re-briefing translators, rechecking in each language, changing layout and proofreading again.

Third, while project managers are skilled at delivering complex multilingual projects, two areas frequently cause delay and extra costs: source files that are difficult to internationalise, and a lack of co-ordination between client and local approval processes. Both can be avoided by involving the localisation company at an early stage: it can advise your advertising agency on providing source material that can be easily localised without major rewriting, new imagery or file engineering and may also be able to handle the local approval process on your behalf.

And, finally, good translation is not a commodity purchase. If you wish to communicate effectively with your customers in local markets, you cannot equate cost with value. Words bought cheaply can end up being very expensive for your business if they have been poorly localised and convey the wrong message. C

Monica Basting is Head of Linguistic Services at Wordbank Ltd, London W1. E: [email protected] W: www. wordbank.com Translation page editor: Janet Fraser. E: [email protected]

Information to be included in a translation brief

Absolute ‘must have’ information Helpful but non-essential information

Source text — final approved version if possible

File format or proposed file formatTarget language(s) by countryServices required — for example, DTPPreferences for language style and mode

of addressClient approval processDelivery dateDelivery formatPurchase order or written confirmation

Background to the project and/or the creative brief

Word countTarget market and audience(s)Marketing communications objectives

and desired responseReference materials for tone, imagery,

style and so onContact details for local approval contacts

and their scope for making changesPrevious or similar projects


�0 Member profile

How long have you been in the business and how did you start?I’m just about to ‘celebrate’ 30 years in technical communication! I started as a technical editor with a systems engineering firm, which was then hiring arts graduates as editors. I soon felt that I needed a technical background to engage fully in the business. (I’d regretted having to ‘drop’ the sciences, so was glad of this opportunity.)

I studied electrical and electronic engineering, with options in computing and in control engineering. I then became a technical author, moving to writing software documentation within software development teams. I really enjoy the combination of use of language and technical subject matter.

I spent several years managing documentation teams and running large software documentation projects. I’ve also presented training courses, developed computer-based training courses and been involved in testing software. I have also worked extensively in developing documentation standards and documentation production metrics.

What is your current role?I’m documentation manager for royalblue financial plc. Fidessa (the company’s suite of products) provides

solutions for trading systems, market data and connectivity for financial institutions worldwide.

Six years ago, I decided to return to writing to stay in touch with technical developments in software and documentation. Now I have a very fulfilling role developing documentation strategy and standards, managing a small team, and writing and editing documents.

My role provides technical challenges and a really good mixture of short-, medium- and long–term targets Also, we have customers worldwide and offices in the UK, Europe, the US and Asia. So there are documents to sort out for Asia at the start of the day, UK and Europe throughout, and we start running around for the US in the afternoons! The sun never sets on royalblue!

What qualifications do you have? BA (Hons) English and Philosophy HNC Electrical and Electronic

Engineering.

What do you like most and least about being a technical writer?I have an enduring interest in commu-nicating accurate information clearly and succinctly at the appropriate level. Since that is fundamental to the technical communicator’s role, my work provides continuing challenges and pleasure. I’m also very keen on guiding developers (and other contributors) towards appre-ciation of careful use of language.

I’m disappointed that I have to spend time ‘debugging’ word-processing tools when new ‘features’ are introduced. I dislike the ‘trial and error’ approach to development in some branches of IT.

What have the biggest changes been over the past five years? The predominance of electronic and

web-based documentation (almost exclusively now, in my recent experience)

The extensive use of integrated Help and the rise of ‘animated’ Help for PC-based user documentation.

What do you expect to change in the next five years?I predict growth in: Single sourcing Wikipedia-style material Growth in the use of English in tech-

nical communication worldwide (in parallel with development of the World Wide Web).

What made you take on the role of book review manager?I started with an interest in the regular feature in Communicator, from which I found discovered books and subject matter that I would not otherwise have seen. I then did a review and was drawn in to the process!

An ISTC member with knowledge of a subject or topic can provide good value with a book review, particularly when the reviewer compares the book with other related titles.

What do you need from members to improve our review coverage?Poornima and I share the review manager’s role. We are always looking for suggestions for books to review and for volunteers to do the reviews.

We invite volunteers for particular books through the ISTC discussion group. I’m also keen to have e-mails from members with specialist and general interests. I’d like to have a growing list of reviewers!

Suggestions for types of book and subject matter are always welcome.

What led to you recent decision to join Council?I’ve been more involved in ISTC activities in recent years, and I’m impressed with the progress in enhancing the professional standing of technical communicators and in promoting formal education and continuing learning within the profession.

I’d like to be of more formal and consistent use to the Institute.

What do you hope to be able to achieve for the ISTC?I have a range of knowledge and experience, which I hope I can pass on to the benefit of others. I will endeavour to make my contribution focused and effective, so that the ISTC does benefit directly and in line with the initiatives of Council.

If you could change career, what would you do instead and why?It’s difficult to imagine not writing. I’d stick with use of language and teach English as a Second Language — maybe somewhere warmer! C

If you have suggestions for books to review, or you would like to volunteer your services as a reviewer, contact Linda and Poornima on [email protected]

In this issue, we meet Linda Robins, one of our book review managers and newly co-opted Council member.

communicator - istc.org.uk · communicator the institute of scientiﬁc and technical communicators...

Documents