This presentation is an introduction to the field of technical writing based on my personal journey and philosophy of documentation, and was presented to the first meeting of Write The Docs Nigeria on February 20, 2021.

1. Technical Writing
What is it like? How can I start?

2. Overview
My technical writing journey
1
2
3
Technical Writing & development
What technical writers do
4 Core concepts
5 How can you start?

3. My Journey into Tech Writing
Student projects Learning about the
field
OSS Projects Paid Projects Full-time
employment
✎ 📚 💻 💰 🏢

4. My Journey as a Tech Writer
Working on a team Small greenfield
projects
Leadership within
a team
Larger greenfield
project
Leading a team
and helping
outside teams
👥 🧱 🔨 🏠 🎤

5. Technical Writing & Development

6. Comparison
Similarities
• Fast-evolving field
• Usually working in
engineering teams to
build products
• Analytical approach to
solving problems
• Attention to detail
Differences
• Technical writers write
less code
• Technical writers may
take on other writing
• Tech writers take on
broader ownership
• Heavier user focus

7. What Technical Writers Do

8. The primary skill of a technical writer must be the
ability to organize information to ensure clarity,
logic order, and comprehensible bodies of work.
Technical Communication Body of Knowledge
https://www.tcbok.org/careers/career-paths/technical-writer/;"Bookshelf at Half Price Books" by D Coetzee is marked with CC0 1.0

9. ● Technical writing
● Editing and proofreading
● Exploring software
● Basic image editing
● Project Management
● Time Management
● Curiosity
Technical Writing Core Skills
"Stack of Books" by Sam Howzit is licensed under CC BY 2.0

10. Other Useful Skills
● Scripting
● Accessibility
● UX Design
● Interviewing subject matter experts
● Facilitation
● Prioritization
● XML or Markdown
● Independent learning
● Video editing
● Teaching
● Code sample creation
● User Research

11. Core Concepts
This section is based on my talk “Delivering documents for all 3 use cases”,
originally presented at Write The Docs Day Australia

12. As a technical writer,
Everything you write should meet a user need.
We call these use cases.
Public Domain Photo from @MetaLab

13. Three Use Cases
Product Discovery
Learning a
brand-new
product for the
very first time
Problem Solving
Completing a
specific task you
already know
exists, or
troubleshooting
something that
doesn’t work
Feature Discovery
Learning a new
feature you’ve
not tried yet, or
new parts of a
feature you
often use

14. Jigsaw Overview
https://www.w3.org/Jigsaw/Doc/Overview.html

15. Product Discovery
Pros
• Friendly,
conversational
• Basic enough for a
beginner to understand
• Situates you within
general tasks

16. Product Discovery
Pros
• Friendly,
conversational
• Basic enough for a
beginner to understand
• Situates you within
general tasks
Cons
• Doesn’t address a
specific task
• Moves slowly and
gives beginner-level
information
• Unclear how much you
can skip (if skippable)

17. Jigsaw Overview
https://www.w3.org/Jigsaw/Doc/Overview.html

18. Help Someone Learn Your Product
● Introduce the why
● At least hint at order
● Contextualize upcoming tasks
● Be efficient, but not terse
● Consider emotional impact: the user is curious
● Be extra-careful about spelling and grammar

19. “Snagit Editor Overview” by TechSmith
https://support.techsmith.com/hc/en-us/articles/360050660491-Snagit-Editor-Overview

20. Feature Discovery
Pros
• More focused
exploration
• Links to related topics
• Still pretty manageable
level of detail
• Introduces acronyms
or concepts

21. Feature Discovery
Pros
• More focused
exploration
• Links to related topics
• Still pretty manageable
level of detail
• Introduces acronyms
or concepts
Cons
• You might not want
this feature
• Typically not very
skimmable
• Won’t get an advanced
user very far

22. ● Chunk the documentation
● Contextualize within the product, but don’t dwell off-topic
● Keep it tight, but friendly
● Go in order
● Keep your promises
Help Someone Learn A Feature

23. “Why are floating-point calculations so inaccurate?” from Python Design FAQ
https://docs.python.org/3/faq/design.html#why-are-floating-point-calculations-so-inaccurate

24. Problem Solving
Pros
• Drop-in content
• Brief and skimmable
• Applies to multiple
browsers or
configurations, with all
necessary detail
• Helps advanced users

25. Problem Solving
Pros
• Drop-in content
• Brief and skimmable
• Applies to multiple
browsers or
configurations, with all
necessary detail
• Helps advanced users
Cons
• Dives in, little context
• Can be overwhelming
to new users
• May create the
impression that the
product is hard to use
or breaks often

26. ● Include the minimum viable explanation
● If skimming will cause problems, warn people
● Test it twice as much as usual
● Consider emotional impact: the user is stuck and probably frustrated
Help Someone Solve A Problem
...and move on ASAP

27. How to start
This is a lot!

28. Network, Learn, and Practice
● Technical-writing-centered communities are great
● General technology communities as well
● Project-based groups around technologies or community projects
● Learn and practice: attend meetups, read articles, and look for chances to
apply what you’re learning

29. Recommended Resources
● Nicole Kelley’s Basics of Technical Writing (Part I) slide deck
● Tom Johnson’s Documenting APIs: A guide for technical writers and engineers
● Google’s Technical Writing courses
● Moscow Institute of Physics & Technology’s Technical Writing course on
Coursera

30. Where to find opportunities
● If you’ve never contributed to opensource before:
https://github.com/collections/choosing-projects
● If you’ve contributed code, but not docs, to opensource, start here:
https://github.com/topics/documentation and look for the tag “good first
issue”
● Role-sharing or projects at work
● Andrew’s about to give you tips on this, too!

31. Questions?

32. Thank you!
● Twitter/Github: @maggiefero
● https://www.linkedin.com/in/margaret
fero/
● WTD Slack: @maggie
● Email maggiefero@gmail.com