Dana Scheider

Senior software engineer at Envato

Dana's presentation (video recording)

Dana's slides

"Are you writing about a complex technical topic, or, will your readers find your topic complex and technical?"

Examples of technical writing

• Documentation (READMEs, QSGs, API docs, Contributor/developer documentation)
• Pull request descriptions (and comments on PRs)
• Request for comment (RFCs)
• JIRA tickets, Trello cards, and issue reports
• Architectural decision records (ADRs)
• Technical books, articles, and blog posts
• Commit messages and code comments

Qualities of Good Technical Writing

• Context

  • Provides necessary background information (to understand what you’re telling)
  • Assumptions about reader’s background or prior knowledge have been validated

• Detail

  • Anticipates and answers reader’s questions
  • Provides all information to readers for what they need to do next
  • Contains enough detail without overwhelming or confusing readers

• Clarity

  • Introduces concepts or ideas in a logical order
  • Uses language as unambiguously as possible (avoiding overloaded terminology, excessive jargon, too many acronyms)
  • Is formatted in a logical, easy-to-follow way (also visually)

• Conciseness

  • Uses no more words than necessary to express each idea or concept
  • Omits details that are unnecessary or will confuse readers

”Writing is a mono-directional medium, it is really important to think as a reader: what someone is going to wonder as they read and answer those questions in the writing."

The goal of good Technical writing

Communicate to readers

• Who is your audience? Consider profession, education, experience, demographics, cultural background
• How homogeneous is your audience?
• Have you really thought of everybody?
  • Non-native speakers are commonly forgotten
  • Juniors learning development history on a new codebase
  • Developers checking git history to solve problems in the future
  • Product managers and business stakeholders (engineers with different knowledge base)
  • The information they need

Identify what your different readers already know

• Identify gaps between readers’ existing knowledge and the knowledge they should have once they read the document
• Write down your assumptions
• Validate those assumptions - get feedback!

What do they need to do next

For example:

• 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

”Time and empathy for readers are the key missing components in much technical writing. A lot of people will not spend the time that’s required to produce quality technical documents and they will look at things too much from their own point of view and not enough from reader’s."

Anti-patterns

• Ambiguous or unclear language
  
  • Overloaded terminology or acronyms
  • Too many acronyms
• Implicit assumptions about reader’s knowledge base - it is very difficult to avoid
• 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 PRs 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
• 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 details
  
  • 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

”Writing is a process, not a product - just like coding is. [...] These are documents that need to be produced over time and not documents that should just be jotted down and then left. Especially when you are working on an actively maintained codebase. You’re going to need to maintain living documents, so thinking of writing as a process and not a product is important."

How to 1o1

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

2. 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 organize your 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 in draft stage: don’t worry about spelling, grammar, conventions or flow just yet
• Focus on the getting ideas out

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

4. Finishing touches

• Re-read your writing again
  • Read the piece as a whole before stopping to make changes
  • Check fo 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!

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

Summary

• 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 organized writing process, starting with analysing your audience, will make your writing more effective