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.
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
👥 🧱 🔨 🏠 🎤
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
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
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)
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
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!