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.
‘So, you have already
screwed up…’
The Intro to Tech Writing
How users typically learn
product
User Interface
Documentation
Customer Support
Why Text?
• (Relatively) cheap
• Easy to search
• Cross-references
• Light-weight
• Better memorisation: the more efforts ...
Questions your doc should
answer
• What is it?
• What is it intended for?
• What is it not intended for?
• What do I need ...
Questions your doc should
answer
• How to check if it’s working or not (even if it’s
obvious)?
• How to set it up to work ...
Two main approaches
Manual
• How to…?
• Explains the process of using
a product
• Good for core functionality
Reference
• ...
Documentation types
Business Rqs
Functional Rqs Specifications
Test Cases
User Guides
User Manuals
Service Manuals
FAQs
Kno...
Where to start
• Define your target audience
• Single out any precautions => Formulate the
disclaimer!
• ’80/20’ rule: user...
The structure of document
• Document purpose (including TA, doc’s structure
and recommendations for its use)
• Product ove...
The structure of document
• Main procedures/operations description
• Customization/personalization
• ‘Acceptance criteria’...
The structure of document

(advanced)
• What’s inside: technologies used, deeper view
• Advanced options (for experienced ...
Recommendations
• EN: IEEE Std 1063-2001
• RU: ГОСТ 19 (ЕСПД)
• and…
Recommendations
• Illustrate! But not too much, that’s not a comic book
• Atomise information: don’t afraid to use lists, ...
No one loves to read
docs
Deal with it. Or quit :)
Upcoming SlideShare
Loading in …5
×

Intro to Technical Writing

176 views

Published on

Technical writing is not so popular profession like, for instance, developer or designer (that was even hard to choose a category for this presentation). But it is important too. Later on I'll try dive deeper into specific questions, with your help, indeed.

There are not so many guides, tips or professional events on how to write documentation, so I've compiled my own experience and other materials I had found into this brief intro.

Published in: Career
  • Be the first to comment

Intro to Technical Writing

  1. 1. ‘So, you have already screwed up…’ The Intro to Tech Writing
  2. 2. How users typically learn product User Interface Documentation Customer Support
  3. 3. Why Text? • (Relatively) cheap • Easy to search • Cross-references • Light-weight • Better memorisation: the more efforts you put to learn anything, the longer you remember it
  4. 4. Questions your doc should answer • What is it? • What is it intended for? • What is it not intended for? • What do I need to make it work? • What should I do to get what I want?
  5. 5. Questions your doc should answer • How to check if it’s working or not (even if it’s obvious)? • How to set it up to work as I want? • What’s inside (be careful!) • What else can it do?
  6. 6. Two main approaches Manual • How to…? • Explains the process of using a product • Good for core functionality Reference • What is…? • Explains specific elements/ features of a product • Good for additional features (like settings, preferences etc.)
  7. 7. Documentation types Business Rqs Functional Rqs Specifications Test Cases User Guides User Manuals Service Manuals FAQs Knowledge Bases How-To’s Support Forums Instructions Internal External Quick Start Guides
  8. 8. Where to start • Define your target audience • Single out any precautions => Formulate the disclaimer! • ’80/20’ rule: users use 20% of functionality 80% of time
  9. 9. The structure of document • Document purpose (including TA, doc’s structure and recommendations for its use) • Product overview: its purpose, description of main functional parts, precautions, disclaimers • Where to start: recommendations for users’ expertise, any preconditions, unboxing/setting up
  10. 10. The structure of document • Main procedures/operations description • Customization/personalization • ‘Acceptance criteria’: how to check if it’s working • Possible errors and ways to solve them
  11. 11. The structure of document
 (advanced) • What’s inside: technologies used, deeper view • Advanced options (for experienced users) • Tips and tricks
  12. 12. Recommendations • EN: IEEE Std 1063-2001 • RU: ГОСТ 19 (ЕСПД) • and…
  13. 13. Recommendations • Illustrate! But not too much, that’s not a comic book • Atomise information: don’t afraid to use lists, tables • Less adjectives • Avoid long sentences and paragraphs
  14. 14. No one loves to read docs Deal with it. Or quit :)

×