Technical Writing: April 28, 2016 Presentation by Emily Flanagan & Introducing Erin Lundstrom The Do’s & Don’ts of Knowledge Base Articles
Technical Writing:
April 28, 2016Presentation by Emily Flanagan & Introducing Erin Lundstrom
The Do’s & Don’ts of Knowledge Base Articles
What is Technical Writing?“Any written form of writing or drafting technical communication used in a variety of technical and occupational fields. Includes communicating about specialized topics, communicating through technology, or providing instructions about how to do something regardless of the task’s technical nature.”
What is Technical Writing?“Any written form of writing or drafting technical communication used in a variety of technical and occupational fields. Includes communicating about specialized topics, communicating through technology, or providing instructions about how to do something regardless of the task’s technical nature.”
AKA most of the writing we do about Emergency Reporting!
GOAL: Convey complex information to another person in the most clear and effective way possible.
Why does it matter?• Important when writing
Knowledge Base Articles• Empowers the user• Helps field calls for support– Simple questions: 16%– Complex questions: 38%
THE DO’S
THE DO’S1. Structure it.
Knowledge Base Outline
THE DO’S1. Structure it. 2. Remember: less is more.
For simplicity’s sake…• Use straight forward instructions– EXAMPLE: • Navigate to the grid where the data is located• Click on the tab labeled “Data Grid”
• Make the process easy for the customer
THE DO’S1. Structure it. 2. Remember: less is more. 3. Use pictures.
EXAMPLE:
Go to the Emergency Reporting Knowledge Base and then click on the Suggest a Feature page.
Go to the Emergency Reporting Knowledge Base and then click on the Suggest a Feature page.
Go to the Emergency Reporting Knowledge Base and then click on the Suggest a Feature page.
THE DO’S1. Structure it. 2. Remember: less is more. 3. Use pictures.
THE DON’TS
THE DON’TS1. Assume anything.
Don’t assume… the reader knows what you’re talking about.
• Explain every step & icon• Provide the most thorough information as
possible
THE DON’TS1. Assume anything.2. Use jargon.
Clarify, clarify, clarify.• Time and place to display your vast vocabulary• Do your best to explain technical terms– EX: Configure Setting Up– EX: Migrate Move
THE DON’TS1. Assume anything.2. Use jargon.3. Underestimate the reader.
“Assume the reader knows nothing. But don’t assume the reader is stupid.” – Ann Handley
• Be an advocate for the customer!• Always use a positive, respectful and
encouraging tone• Do not be condescending:– “If you don’t already know where ___ is, then
click….”
THE DO’S1. Structure it. 2. Remember: less is more. 3. Use pictures.
THE DON’TS1. Assume anything.2. Use jargon.3. Underestimate the reader.
Happy KB Article Writing!