1. Technical Writing:
April 28, 2016
Presentation by Emily Flanagan &
Introducing Erin Lundstrom
The Do’s & Don’ts of
Knowledge Base Articles

2. 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.”

3. 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!

4. GOAL:
Convey complex
information to
another person in
the most clear and
effective way
possible.

5. Why does it matter?
• Important when writing
Knowledge Base Articles
• Empowers the user
• Helps field calls for support
– Simple questions: 16%
– Complex questions: 38%

6. THE DO’S

7. THE DO’S
1. Structure it.

10. Knowledge Base Outline

11. THE DO’S
1. Structure it.
2. Remember: less is more.

12. 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

13. THE DO’S
1. Structure it.
2. Remember: less is more.
3. Use pictures.

14. EXAMPLE:
Go to the Emergency Reporting Knowledge Base
and then click on the Suggest a Feature page.

15. Go to the Emergency Reporting Knowledge Base and
then click on the Suggest a Feature page.

16. Go to the Emergency Reporting Knowledge Base and
then click on the Suggest a Feature page.

17. THE DO’S
1. Structure it.
2. Remember: less is more.
3. Use pictures.

18. THE DON’TS

19. THE DON’TS
1. Assume anything.

20. Don’t assume… the reader knows
what you’re talking about.
• Explain every step & icon
• Provide the most thorough information as
possible

21. THE DON’TS
1. Assume anything.
2. Use jargon.

22. 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

23. THE DON’TS
1. Assume anything.
2. Use jargon.
3. Underestimate the reader.

24. “Assume the reader knows nothing.
But don’t assume the reader is stupid.”
– Ann Handley

25. • 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….”

26. THE DO’S
1. Structure it.
2. Remember: less is more.
3. Use pictures.

27. THE DON’TS
1. Assume anything.
2. Use jargon.
3. Underestimate the reader.

28. Happy KB Article Writing!