Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Technical Writing In A Nutshell


Published on

In order to develop my technical writing skills, I undertook a number of technical writing courses over the course of a number of months. Based on the research I carried out, I put together a useful slideshow that summarized what I learned so I could present this to the team where I work.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Technical Writing In A Nutshell

  2. 2. Presentation Goals • Get to know the audience you are writing for • Make content easy to understand • Improve grammar and punctuation • Improve use of clear and concise language • Learn the benefit of a style guide • Learn how to give and receive feedback
  3. 3. Learning Topics 1. Audience Analysis 2. Elements of Structure 3. The Mechanics of Writing 4. Characteristics of Good Writing 5. Style Guides 6. Editing
  4. 4. 1. Audience Analysis
  5. 5. 1. Audience Analysis • Categorize your audience: • Expert, Technician, End User, Executive or Management • Consider the prior knowledge of the audience: • Will they be familiar with technical jargon or do all aspects need to be described? • Consider the motivation of the audience: • Why is this product or service being used? • Consider impediments that impact how your audience reads the content: • Work environment, hearing or visual impairments
  6. 6. 1.1 Develop User Profiles • User Profiles and/or User Stories give a clearer understanding of the audience. • A User Profile: • Describes the typical user of this product or service • Contains general information – job title, level of knowledge, motivation, impediments • A User Story: • Describes a more specific real or imagined person that uses this product or service • Contains detailed information – working environment, attitudes, interests • The User Profile and User Story can be referred back to at each stage of the technical writing process.
  7. 7. 2. Elements of Structure
  8. 8. 2. Elements of Structure • To make content easy to find: • Break up large blocks of information • Aim for one chunk per idea • Group related chunks of information • Use headings to provide context • Use noun-based headings for explanatory information • Example: A user can log into an app if they have an account • Use verb-based headings for procedural information • Example: Perform an update by selecting this option.
  9. 9. 2. Elements of Structure ctd. • To make content easy to understand: • Use bulleted lists when order is not important • Use numbered lists when order is important • Include an introductory sentence followed by a colon (like I did with this portion of text).
  10. 10. 2. Elements of Structure ctd. • To make content easy to read: • Establish a hierarchy of fonts and use them consistently • Use a sans serif font for on-screen text • Use bold to emphasise key words, a note, or a caution • Use italics to indicate a quote or expression in another language • Use emphasis sparingly
  11. 11. 3. The Mechanics of Writing
  12. 12. 3. The Mechanics of Writing • A sentence is an expression of a complete idea. • Limit each sentence to 1 idea. • A run-on sentence consists of 2 or more independent clauses connected without appropriate punctuation or conjunction. • Avoid run-on sentences: • Example: I love creating support tickets I would do it all the time if I had the time. • Revised: I love creating support tickets. I would do it all the time if I had the time. • Be consistent in your use of tense. • Spelling, grammar, and punctuation should be correct. • Avoid the use of idioms.
  13. 13. 4. Characteristics of Good Writing
  14. 14. 4. Characteristics of Good Writing • Use clear and concise language. • Make content clearer by translating jargon into plain language. • Choose short, familiar words over long, unfamiliar words. • Use the active voice in your writing by: • Searching for sentences that contain any form of the verb ‘to be’ • Rewriting them so the subject performs the action. • When writing instructive text, start each sentence with a verb. • At the first instance of an abbreviation or acronym, state the full term and introduce the abbreviation or acronym in parentheses.
  15. 15. 5. Style Guides
  16. 16. 5. Style Guides • A style guide is a document that contains standardized conventions for use of font, layout, color, etc. • The benefits of a company style guide are numerous: • It provides a collective voice for the company • It generates a more professional piece of content to distribute to customers • It provides efficiency when creating and distributing content • Widely used style guides include: • The Chicago Manual of Style • The Oxford Guide to Style • Microsoft Manual of Style
  17. 17. 6. Editing
  18. 18. 6. Editing • Readability tests are useful to review your work. • Flesch-Kincaid readability tests • Editing can improve your writing skills. • To self-edit your own writing: • Use editing tools to correct spelling, grammar – spell check in Word or similar • Create an editing checklist of your most common writing errors
  19. 19. 6. Editing ctd. • To perform a peer review of someone else’s writing: • Distinguish between a suggested improvement & a required change • Be objective • Use track changes or commenting in Word or Google Docs • Your feedback meaning should be clear – offer a solution to an issue. • Be open to discussing your feedback with peers.
  20. 20. Useful Resources • Grammarly - • Bullet Journal – • Chicago Manual of Style - • More About Me -