DEIF s style guide A case story. Jeanine Shepstone Technical writer

Transcription

1 DEIF s style guide A case story Jeanine Shepstone Technical writer

2 Let me tell you a (case) story... Once upon a time... What we really want The story so far Happily ever after? Sneak a peek Examples Which might give you nightmares!

3 Once upon a time... Technical writing a new discipline at DEIF DEIF is over 80 years old About 400 products on our website First dedicated tech writer employed 3 years ago Three style guide revisions in 3 years And working on the 5th version

4 What we really want Relevant info Including relevant examples Complete reference for writers Faster training Daily efficiency Update regularly Use with terms, XML templates, stencils

5 Style guides: Evolve or created?

6 The story so far Revision A (37 pages) From InDesign to the tech doc system Relevant examples Best practises from everywhere Reviewed by everyone Revision B (91 pages) Lessons learned, image guidelines Revision C (118 pages) Lessons learned, tool change, XML and style sheet info, XML templates

7 Happily ever after? Not quite: The style guide story s not finished yet Three dedicated technical writers Meet for an hour every one/two months Issues from the last month/two Language and phrases Images Standard descriptions Review new terms Use everyone s brains

8 Sneak a peek Technical writing principles Includes business case, modular writing, review Technical writing tools Intro to DEIF s tools DEIF style Document types and content Hardware and software descriptions Legal Easy to understand (simple & good writing) Company language Numbers Units Punctuation Drawing and image guidelines DITA XML and style sheet elements

9 Some examples Company language Capitalisation Date and time Document contents Trademarks Sequence diagrams Active, direct language

10 Company language British English Also known as English We synchronise. We NEVER synchronize. We are honoured to use colour and write analogue.

11 Capitalisation Is It Just Me, Or Are Too Many Capitals Stressful? Tech doc pays attention to this. Tech doc cleans up the product HMI.

12 Date and time Tech doc researched the best practise. Tech doc encourages the best practise for HMI.

13 Document contents

14 Trademarks

15 Sequence diagrams Before guidelines: No consistency, low clarity Guidelines, including text descriptions: 4 pages

16 Active, direct language

17 Passive voice in politics "Mistakes were made." President Nixon, taking responsibility for Watergate

18 Passive voice in tech doc? If more plant connections are wanted to be synchronised to, the plants will have to be allowed to be parallel, and the plants will have to be set for run all mains. If then some mains are wanted to be synchronised and some not, the ones that is not wanted to be synchronised, will have to be excluded, which can be done with the exclude parameter or from M-Logic. (2 sentences, 69 words)

19 The zombie test

20

21 ... with zombies... If more plant connections are wanted by zombies to be synchronised to by zombies, the plants will have to be allowed by zombies to be parallel, and the plants will have to be set by zombies for run all mains. If then some mains are wanted by zombies to be synchronised by zombies and some not, the ones that is not wanted by zombies to be synchronised by zombies, will have to be excluded by zombies, which can be done by zombies with the exclude parameter or from M-Logic. (2 sentences, 69 words, 10 passives!)

22

23 Without zombies... If you want the controller to synchronise more plant connections, you have to allow the plants to be in parallel, and set them to run all mains. If you then want the controller to synchronise some mains, but not synchronise others, you must use the exclude parameter or M-Logic to exclude the plant connections that you do not want the controller to synchronise. (2 sentences, 63 words (6 fewer), all actors identified)

24 (the eradication of zombies and) Style guide: For a happier planet