Technical writing is rarely taught in code schools or listed among the qualifications for an engineering job. Yet developers rely heavily on documentation to use the tools they need to use. Not only that, decisions about which tool to use often take into account the availability of quality documentation. It’s important not to leave the task of writing docs to technical writers who may not fully understand the underlying technology or use cases. This talk will teach you the basics of technical writing–from tutorials and API reference guides to pull requests, release notes, and even code comments - so you can increase adoption of your software and keep the developers using it happy.

1. The Joy of Docs:
Technical Writing
for Developers and
Engineers
@DanaScheider (she/her)

2. Basics of Communication
● Transfer of information
● Sender → Message → Recipient
● Ease and effectiveness of communication are affected by
many factors:
○ Language
○ Culture and subculture
○ Demographic factors
○ Socioeconomic factors
○ Assumptions by participants about each other
○ Emotions and other personal factors
○ Medium (document, e-mail, face-to-face, video call, voice call, SMS)

3. Writing that describes or
informs about complex
technical topics

4. A Kind of Writing, not a Kind of
Document
Technical writing is not limited to
technical documents.
Technical writing can be present in e-
mails, memos, Google docs,
slideshows, code comments, online
message boards and many other
formats.
Are you writing about a complex
technical topic, or, will your readers
find your topic complex and
technical?

5. Examples of Technical Writing
● Documentation
○ READMEs
○ Quick-start guides
○ API docs
○ Contributor/developer documentation
● Pull request descriptions (and comments on PRs)
● Requests for comment (RFCs)
● JIRA tickets, Trello cards, and issue reports
● Architectural decision records (ADRs)
● Technical books, articles, and blog posts
● Commit messages & code comments

6. We cannot work without
clear, concise, detailed
and unambiguous
technical communication
in writing.

7. Technical writing is a skill
we don’t teach to
engineers.

8. Qualities of Good Technical Writing
● Context
○ Provides necessary background information
○ Assumptions about readers’ background or prior knowledge have
been validated
● Detail
○ Anticipates and answers readers’ questions
○ Provides all information readers need to do what they need to do
next
○ Contains enough detail without overwhelming or confusing readers

9. Qualities of Good Technical Writing
● Clarity
○ Introduces concepts or ideas in a logical order
○ Uses language as unambiguously as possible
○ Is formatted in a logical, easy-to-follow way
● Conciseness
○ Uses no more words than necessary to express each idea or
concept
○ Omits details that are unnecessary or will confuse readers

10. Efficiently communicate
to readers the
information they need to
do whatever they need to
do next.

11. Communicate to Readers
● Who is your audience?
○ Specific individual(s)
○ Professional backgrounds
○ Educational backgrounds
○ Amount of experience in their roles
○ Demographic and cultural factors
● How homogeneous is your audience?
● Have you really thought of everybody?
○ Juniors learning development history on a new codebase
○ Developers checking git history to solve problems in the future
○ Product managers and business stakeholders

12. The Information They Need
● Identify what readers already know
○ Dependent on knowing broadly who your readers are
○ Likely to differ for different readers and different types of
documents
○ Are you sure they know that?
● Identify gaps between readers’ existing knowledge and
the knowledge they should have once they have read the
document
● Write down your assumptions
● Vet those assumptions (get feedback!)

13. What They Need to Do Next
● Why is each reader reading your writing?
● What is each reader doing when they read your writing?
● What will their next steps be after reading it?
○ Reviewing your PR
○ Using a class or method from your library in their code
○ Verifying that a product meets specifications
○ Writing a client for your API
○ Informing business stakeholders about the status of a project
○ Commenting on your RFC
○ Contributing to your open source project
● Does your writing give them what they need to take
those steps?

14. Time and empathy for
readers are the key missing
components in much
technical writing.

15. Learn to recognise and
fix anti-patterns before
putting your writing in
front of readers.

16. Anti-Patterns
● Ambiguous or unclear language
○ Overloaded terminology or acronyms
○ Too many acronyms
● Implicit assumptions about readers’ knowledge base
● Missing background information or context
○ Links to other documents that came before this one
○ Links to Trello cards/JIRA tickets with background information
○ Links to relevant pull requests or release notes
○ Details of what prompted a change to be made or what problem it
solves/will solve
○ Links to specific lines of code being referenced
○ Glossaries defining terms and spelling out acronyms

17. Anti-Patterns
● Missing details
○ How the software you’re writing about interacts with other tools or
systems
○ Type and structure of parameters and output values of functions or
methods (when documenting a library or writing contributor docs)
● Excessive detail
○ What’s excessive depends on what you’re writing and why
○ API docs should include minimal/no references to internals
○ Ask yourself if any of your readers are likely to wonder why this
information is being included or how it relates to the whole

18. Writing is a process, not a
product.

19. Before You Write
● Do all pre-writing work in a notebook or Google doc
● Ask yourself why you are writing this piece
● Identify who your readers are and what they know
● Validate assumptions you’ve made about your readers
and their prior knowledge
● Determine what you want readers to be able to do
● Create an outline with points you want to cover
● Brainstorm questions readers might ask about the
information you’re including
○ Add answers to those questions to your outline

20. Writing a Draft
● Your draft is not your final product
○ Avoid putting your draft in the same place your final product will be
○ You will copy and paste when you are done revising and editing
● Collect and organise the products of pre-writing
● Flesh out your outline
○ May become an expanded outline before it is a draft
○ Move, add or remove sections if something else makes more sense
● Content over form
○ Don’t worry about spelling, grammar, conventions or flow
● Focus on the getting ideas out

21. Revising Your Document
● Re-read your draft at least once
● Make notes
● Ask yourself:
○ Is this information in the most useful form to readers?
○ Does the information flow in a logical way?
○ Is the language clear and unambiguous?
○ Are acronyms spelled out or defined?
○ What am I choosing to leave out?
● Still don’t worry about spelling, grammar or punctuation

22. Finishing Touches
● Re-read your writing again
○ Read the piece as a whole before stopping to make changes
○ Check for context, detail, clarity and conciseness
○ Ensure spelling, grammar, and punctuation are correct
○ Make any necessary changes to structure or format
● Ask for feedback
○ Especially important on longer or more detailed pieces of writing
○ Feedback should be from people similar to those you expect to read
your work
● Copy and paste into the final place it needs to go
○ Remember you’re doing all the draft work in a separate place!

23. Longer or more
complex pieces
require more
attention to the
writing process.

24. Recap
● Technical writing is any writing that describes or informs
about complex technical topics
● Examples range from books to RFCs to code comments
● Knowing about your readers, what information you are
conveying to them and why are the most important parts
of the technical writing process
● Adhering to an organised writing process, starting with
analysing your audience, will make your writing more
effective

25. Thanks!
Contact me:
Dana Scheider (she/her)
dana.scheider@envato.com
@DanaScheider on Twitter