Technical Writing Fundamentals

Cheat Sheet

Some of the panels below have explainer videos to remind you what we covered on the course. Tap the panels to see!

 

Core Principles

Four Writing Types

Match your purpose to the right type

  • Reference: Transfer information (installation manuals, API docs) - doesn't need to be interesting
  • Tutorial: Transfer skills through examples - judged on what readers can do afterwards
  • Pitch: Cause action (sales, job applications) - about one thing, focused on audience benefit
  • Story: Transfer experience through narrative - project post-mortems, incident reports

Aristotle's Idea Machine

Three sources of ideas for any topic

  • HEAD (Logos): Facts, data, logic - use the 7 W's: Who, What, When, Where, Why, How, How Much
  • HEART (Pathos): Emotions - 6 basic emotions: anger, disgust, fear, joy, sadness, surprise
  • BEHAVIOR (Ethos): Character, ethics, actions - what people do, not just what they feel

Capture ideas on a mind map using paper and pen - unordered thinking tool that reveals connections and focus areas.

Adding Motivation

The Globus Pallidus problem

  • The Brain's Filter: Globus Pallidus blocks non-survival information
  • Problems = Survival Info: Associate writing with problems to bypass the filter
  • Find Problems: Sift through your ideas to identify problems being caused or solved
  • One Problem Per Section: Each section should solve exactly one problem

Key insight: Without problems, writing feels "crashingly dull" - the brain actively blocks it as unimportant.

The OODA Loop

From fighter pilot tactics to writing structure

  1. Observe: The objective - what someone wants to achieve (seems reasonable/self-evident)
  2. Orient: The problems that prevent achieving the objective
  3. Decide: The solution/plan to overcome those problems (usually one sentence)
  4. Act: The detailed implementation - where most of your content lives

Write backwards: start with what you want to explain (Act), then build the motivation around it.

The 10-Minute Rule

Concentration spans and section length

  • Attention Limit: Most people can concentrate for about 10 minutes on one problem
  • Written Equivalent: About 4-5 pages of text per section/arc
  • Break Long Sections: If longer, find additional sub-problems to create new sections
  • Regular Refreshing: Change topics/approach every 10 minutes to maintain engagement

Refining Your Outline

Triage your sections

  • OK: Section stays in main content - core to your message
  • Remove: Section gets cut entirely - not essential or off-topic
  • Demote: Move to appendix, GitHub, or supplementary material - useful but not critical
  • Apply 10-Minute Rule: Break overly long sections into smaller problems

Tent Pole Sentences

From outline to body text

  1. Take each bullet point from your outline
  2. Write key thoughts as short sentences in order
  3. Don't worry about grammar or style yet
  4. Expand each tent pole sentence into one or more paragraphs

    5. This is the "watching daytime TV while typing" stage

Making Text Skimmable

People navigate before they read

  • Headings First: People read headings to navigate - make them meaningful on their own
  • Visual Elements: Diagrams, code samples, and images get attention before body text
  • Structure Text: Use bullet points, sidebars, pull quotes, and box-outs
  • Thumbnail Test: If all pages look the same when shrunk, add more visual structure

Show, Don't Tell

Reveal your "car chase" in stages

  • Find Your Car Chase: The code, diagrams, or processes people came to see
  • Start Simple: Show basic version first, then add complexity
  • Repeat and Expand: Don't worry about length - people want to see the details
  • Visual Metaphors: Use consistent imagery (like padlocks for security)

Mind Mapping Tips

Better thinking tools

  • Use Paper: Physical mind maps work better than software
  • Four-Color Pen: Different colors for different types of ideas
  • Reserve Red for Problems: Highlight the golden ideas that create motivation
  • Unordered Thinking: Avoid the psychological bias of lists
  • Look for Connections: Mind maps reveal relationships between ideas

Mind maps focus your ideas; they help you find what your writing is about.

Beating Writer's Block

Common causes and fixes

  • Apathy: Topic feels dull → You haven't found the underlying problem being solved
  • Fear of Failure: Afraid to start → Write a deliberately bad version first
  • Can't Start: First sentence paralysis → Write the introduction last
  • Get Distance: Pretend you're editing someone else's bad draft

The Writing Process

Four stages from blank page to finished piece

  1. Skeleton (Ideas): Use Aristotle's three sources to generate ideas on mind map
  2. Muscles (Motivation): Find problems, create OODA sequences for each section
  3. Trim Fat (Edit): Apply 10-minute rule, triage sections (OK/Remove/Demote)
  4. Skin (Write-up): Use tent pole sentences, make it skimmable, show don't tell

Lovingly crafted in Glorious Stereophonic HTML by David Griffiths.