Post on 06-Jul-2018
About Matthew Bin
Graduated with B.A. in English Literature (Honours), April 1996
Began M.A. in English Literature, September 1996
Panic set in, November 1996
Became technical writer, February, 1997
Graduated with M.A. in English Literature, September 1997
Hired by Compaq Canada, September 1997
Employers and clients include Compaq, MOE, MMAH, Fidelity Investments,
Descartes Systems Group, i2 Technologies, Talent Technology Group
Well over 1 million words of paid technical writing by 2006
What is Technical Writing?
Any documentation that describes or instructs on a technical subject, device,
or product
Can include:
User manuals
Technical manuals
Reference materials
API guides
Release notes
Knowledge base articles
Configuration/setup guides
FAQs
Wikis
Web Pages
And more…
What is Good Technical Writing?
What do you think good technical writing is?
Good technical writing has qualities like…
Clarity
Completeness
Ease of reading
Ease of use
Logical organization
(What else?)
Why Technical Writing?
Adds value to your products
Adds value to your brand
Increases customer satisfaction and retention
Planning Your Document
Typically, technical documents are written the wrong way
“Once upon a time…”
The result: an unhappy ending
Planning Your Document:
How to Create Your Plan
How do you produce every single other technical product?
Research needs
Understand technical requirements
Create a specification
Why not the same for your documents?
Planning Your Document:
The Document Specification
What are we creating?
Who is it for?
Why are we creating it?
Where is it going?
What does it contain?
Structuring Your Document
Writing is not words
Writing is organizing thought
A strong structure means a strong document
Think about all the information you need to present BEFORE you start to put
it together
Structuring Your Document:
Headings
Divide your document into logical groups
Tasks
Features
Groups of users
Use Headings
Headings, sub-headings – groups and sub-groups
Structure reflects content
Don’t over-structure
The depth spiral
Don’t go too deep – three or four levels at most
Same kind of content needs to be at the same level
Structuring Your Document:
Formatting
Numbering, fonts, and other fancy stuff can help, but…
Heading numbers
Do they add anything?
Indents, text size
Can help to show organization
Fonts and formatting
VERY easy to overdo
One font for headings, one for text, one for code – THAT’S ALL
Approaching the Writing
The natural way to write about a product: describe it
Product > Feature List > Description of each feature
Users do not need this
Approaching the Writing:
What to Do Instead
What are we missing?
THE USER
From the user’s point of view:
I need to perform a task
I don’t know or care about features
I don’t care about your product – my tasks are not your tasks
Function-based or use-based approach
Approaching the Writing:
Function-based Approach
Puts the user’s needs first
Helps the user find content in the document
Helps to position the content to the user’s advantage
Minimizes excess documentation
…can improve product design!
Approaching the Writing:
Where to Start?
Start from the user’s goal
Work backwards to find the process path
Describe only one task at a time
Name the section after what the user needs to do
Approaching the Writing:
How to Proceed?
Walk through the task; describe each step
Add notes, if/thens, screen shots only if needed
Screen shots and diagrams must help the text – minimize them
Approaching the Writing:
Quality Assurance
After you’re done, follow your own instructions and try to complete the task
If it is something the user has to do to complete the steps, include it in the
text
If you do not test your own documentation…
Tech Writer Tips:
Consistency
Terminology
Use the same words for the same things (e.g. “Screen”, “Window”, “Interface” –
pick one and stick with it)
Don’t get fancy; finesse is for poets
Audience
Talk to the same person
Make the same assumptions, stay on the same level
Conclusion
Technical writing is about organization
Language, writing skills are not barriers to good documentation
Make a plan, and focus on the user