Introduction to Technical Writing Part 1

1
Introduction to Technical Writing Part
1

• Lynn Jackson
• August 21, 2007

2
Agenda August 21

• Technical writing defined
• Position within the corporation
• Value of technical writing to the corporation
• Skills
• Tools
• Tasks
• Process
• Value of writing well
• Writing exercise (15 min.)

3
Terms
4
My Background

• Over 18 years experience as a technical writer
  and marketing writer both as an employee and a
  contractor
• Cognos, Newbridge/Alcatel
• Contract work for the federal government, defence
  contractor, technology start-up
• Currently employed as a tech writer at Meriton
  Networks

5
Technical Writing

• A specialized, structured form of business
  writing that presents information to help readers
  perform a task or solve a problem
• Characteristics
• Clear and concise easily understood
• Accurate factual
• Correct follows grammatical and technical
  conventions
• Comprehensive contains all necessary info.
• Usable includes navigation aids e.g. TOC,
  headings, subheadings, indexes

6
Position within the Corporate Structure

• RD - usually
• Advantage Proximity to designers to understand
  content
• Disadvantage Limited customer contact
• Customer support - sometimes
• Advantage Better understanding of customer needs
• Disadvantage More difficult to foster
  relationships with SMEs

7
Value to the Corporation

• Well-written and accurate documentation
• An integral part of the product
• Enhances the customer product experience,
  contributing to overall satisfaction
• Part of the customer support strategy, reducing
  support costs
• Speeds up customer acceptance of products
• In start-ups, it may be the first product shipped
  to the customer

8
Cost to the Corporation

• Is usually a cost center (does not produce
  revenue)
• Poorly written or inaccurate documentation
• Contributes to customer frustration with the
  product and the company thus is a cost
• Projects a negative image of the product

9
Technical Writing Dept. Organisation (1)

• Large Companies
• Director - departmental strategy and direction
• Manager(s) - schedules, QC
• Editor(s) - QC
• Writers (Junior, Intermediate, Senior)
• Information Architect(s) - document design
• Illustrator(s) - create illustrations
• Usability tester(s) - test docs with the product

10
Technical Writing Dept. Organisation (2)

• Medium/Small Companies
• RD Director
• Manager writes, schedules, QC
• Writer (junior, intermediate, senior)
• Illustrator - create illustrations (may be
  contractor)

11
Tech Writer Career Path

• Can be an entry point for positions in
• Tech Docs Management
• Tech Docs Information Architecture
• Product testing
• Marketing, marcoms
• Course development, training
• RFP writing
• Sometimes help desk, product management, and sales

12
Fiction

• How hard can it be? I can write in English
• Tech writers pretty up technical specifications
• Tech writers cannot possibly write knowledgeably
  about a complex subject

13
Truth

• Tech writing is a formal discipline numerous
  programs exist at colleges and universities
• SMEs sometimes have limited language and writing
  skills
• Technical writers provide the most effective way
  to transform technical information into user
  documentation
• Famous writers who were also tech writers
• Kurt Vonnegut Slaughterhouse Five, etc. - GE
• Amy Tan Joy Luck Club Nortel
• Thomas Pyncheon Mason Dixon - Boeing

14
Professional Associations

• Society for Technical Communication (STC)
• www.stc.org
• Eastern Ontario chapter of the STC
• www.stceo.org
• Editors Association of Canada
• www.editors.ca/pub/so.htm

15
What Tech Writers Do

• Study design docs/interview SMEs
• Analyze the target audiences needs
• Create a documentation project plan
• Produce a draft document for review
• Produce or arrange for illustrations, charts,
  etc.
• Edit, standardize, revise material prepared by
  other writers
• Prepare material for publication (print or
  electronic form)
• Test products and conduct usability studies

16
Outputs

• User/Installation guides
• Online help
• Reference guides
• Developer guides (e.g. APIs)
• Release notes
• Web page content (intranet and extranet)
• Courseware and training material

17
Key Tech Writer Skills (1)

• Written communication writing and editing
• Verbal communication interviewing SMEs
• Research product details
• Technical aptitude interpret complex technical
  material

18
Key Tech Writer Skills (2)

• Attention to detail quality
• Timeliness/productivity tight deadlines
• Organization/multi-tasking conflicting
  priorities
• Presentation skills
• Flexibility
• Sense of humor because writers always aiming at
  a moving target

19
Tools of the Trade (1)

• Adobe
• FrameMaker (document creation and management)
• Illustrator (technical illustrations)
• Acrobat (PDFs)
• Microsoft Office Suite
• Word (release notes, feedback from SMEs, etc.)
• PowerPoint (team presentations and training)
• Excel (estimating and planning)

20
Tools of the Trade (2)

• Quadralay Webworks (online documents)
• JASC PaintShopPro (screen captures, graphics)
• Snagit (screen captures)
• Macromedia Robohelp (on-line help)
• Visio (diagrams)
• CorelDraw (illustrations)
• Other tools
• Unix OS host for software products
• HTML and XML
• Java, CGI scripting
• Dreamweaver - web content

21
The Documentation Cycle
PLM and RD
Technical Documentation
22
The Writing Process

• Plan 25
• Design 25
• Draft 25
• Revise 25

23
Writer Tasks PLAN (1)

• Perform audience analysis
• Determine intended users
• Identify user level of education
• Identify what users will do with the document
• Reference, Quick start, Installation Guide, etc.
• Linguistic or cultural issues
• Simplified (controlled) English

24
Writer Tasks PLAN (2)

• Determine the purpose of document
• Assist users to perform a specific task?
• Help them understand something?
• Influence their thinking?
• Inform them of something?

25
Writer Tasks PLAN (3)

• Determine the circumstances in which the readers
  will use the document. Will they
• have any background knowledge?
• be reading the material via print or screen?

26
Writer Tasks PLAN (4)

• Create document plan and schedule
• Research
• Study design specs
• Interviews with SMEs
• Hands-on study of SW/HW
• Determine
• Document type and components
• Media
• Paper
• Online
• Web

27
Writer Tasks - DESIGN (1)

• Decide on
• Textual elements
• E.g. Font types, lists, matrices
• Graphic elements
• E.g. Graphs, screen captures, icons
• Document elements
• E.g. front matter, intro, TOC, glossary

28
Writer Tasks - DESIGN (2)

• Many components to consider, for example
• Page layouts, including margins
• Headings (three or four levels may be numbered)
• Headers and footers
• Paragraph styles (regular and indented)
• Screentext and command line styles

29
Writer Tasks - DESIGN (3)

• Many components to consider, for example
• Lists (numbered and bulleted)
• Table styles (title, heading, text, list, table
  notes)
• Illustrations (title, size/resolution, page
  placement)
• Note styles (warnings, cautions, footnotes, etc.)
• Resources
• Microsoft Manual of Style for Technical
  Publications
• The Gregg Reference Manual

30
Writer Tasks - DRAFT (1)

• Create documentation using standard information
  structuring techniques, (Information Mapping).
• Uses seven basic categories of information
• Procedure
• Process
• Structure
• Concept
• Principle
• Fact
• Classification

31
Writer Tasks - DRAFT (2)

• Use information types
• Headings
• Paragraphs
• Tables
• Bulleted lists
• Numbered lists
• Graphics
• Chapters
• Appendices

32
Writer Tasks - REVISE

• First revision
• considers document structure
• Second revision
• considers style and grammar

33
Writer Tasks - Related Activities (1)

• Single sourcing
• Desktop publishing
• Indexing
• Glossary

34
Writer Tasks - Related Activities (2)

• Technical illustration
• Web site development or maintenance
• Usability testing
• Test plan creation and product verification

35
Writing Well is a Valuable Skill

• The ability to express yourself clearly is
  indispensable in todays job market
• Tech writing principles apply to all forms of
  communication
• Functional specifications
• Email
• Powerpoint presentations
• RFPs
• Resumes, etc.

36
Now the Fun Part
37
Exercise - Wordiness (1)

• In the event that the project involves the
  necessity of your traveling out of town, you will
  be afforded an opportunity of drawing an advance
  against pay.
• If the project requires you to travel, you may
  draw an advance against pay.

38
Exercise - Wordiness (2)

• He found it necessary to negotiate with a large
  number of former colleagues during the time that
  the merger was being arranged.
• He had to negotiate with many former colleagues
  during the merger arrangements.

39
Exercise - Wordiness (3)

• They had to make a request for reservations a
  week prior to their visit, due to two large
  conventions in the city.
• They had to request reservations a week before
  their visit because of the two large conventions
  in the city.

40
Exercise - Restructuring

• Post-It Notes restructuring exercise
• Take 15- 20 minutes
• Arrange the information in logical order
• Eliminate redundancy and wordiness
• Add headings, paragraphs, tables, bulleted lists,
  numbered lists

41
Questions
42
See you on August 28