#notes/writing #topic/technical-writing
How Writing User Guides is Like Philosophy
Subtitle ideas
- Exploring Every Path to Understanding
- How Documents Anticipate Questions Before They're Asked
- User Documentation as a Philosophical Exercise
I. Introduction: The Unexpected Parallel
- Most people think writing user guides is about listing steps, but it's really about anticipating human action
- Like philosophy, documentation requires considering multiple interpretations, possible objections, and alternative paths to truth (or in this case, successful outcomes)
- Writing good documentation is a philosophical exercise requiring empathy, reasoning, and anticipating counter arguments
"The unexamined life is not worth living." - Socrates | "The unexamined workflow will confuse your users." - Every tech writer, probably
"Doubt is the origin of wisdom." - René Descartes | "Testing every possible user action is the origin of great documentation."
"All men by nature desire to know." - Aristotle | "All users by nature desire to understand, not just follow directions."
II. Shared Foundations: Inquiry and Clarity
- In philosophy, clarity and structure ensure users can act with confidence
- Both disciplines rely on:
- Defining terminology clearly and avoiding ambiguity
- Establishing assumptions
- Creating a logical flow where one idea leads into the next seamlessly
III. Anticipate the Counterarguments
- Philosophers ask: What if I’m wrong? What if someone disagrees?
- Writers ask: What if the user tries something different? What if they misunderstand this step?
- Both require considering alternative perspectives
- Users might take unexpected paths through a workflow
- Philosophers explore opposing viewpoints to strengthen their reasoning
- Good documentation, like a strong argument, preempts confusion before it arises
Both are iterative journeys toward shared understanding: one through logic, the other through usability.
- Philosophy: Thesis → Antithesis → Synthesis
- Documentation: User Goal → Error Path → Resolution
| Debate | Documentation |
|---|---|
| Premises: Defined starting assumptions | Prerequisites: Software, permissions, context |
| Thesis: A central claim or question | User Goal: The task or outcome the user wants |
| Dialectic Process: Explore every angle | Review: Validate every workflow |
| Antithesis: The counterargument | Error Path: What happens when it doesn’t go as planned |
| Synthesis: A new understanding that resolves both | Resolution: A clear, tested path to success |
IV. Empathy as Logic
- Philosophy often hinges on understanding why people believe what they do
- Documentation hinges on understanding why users behave or think a certain way
- Discuss “user empathy” as parallel to “philosophical empathy”
- Understanding the human behind the question
- Designing for frustration, curiosity, or error as much as for success
V: Every Path, Every Possible Interpretation
- Philosophical debate explores multiple paths to the same conclusion
- Writing user guides means mapping all possible user journeys:
- Alternative entry points (different menus, different devices)
- Conditional steps (if X, then Y)
- Edge cases (exceptions to the rule)
- Show how this mindset creates resilient, inclusive documentation
VI. Searching for the Why Behind the How
- Philosophy seeks why the world works the way it does
- Documentation should help users understand why a process works, not just how to do it
- When users understand reasoning, not just steps, they become more autonomous, skilled, knowledgeable
- This is where documentation transcends instruction and becomes learning
VII. The Philosophical Mindset of a Writer
- The best writers question their own assumptions, anticipate the unknown, and refine endlessly.
- Writing a user guide isn’t about giving answers, it’s about asking possible questions first
"We do not learn from experience... we learn from reflecting on experience." - John Dewey | "We do not write great docs from first drafts... we write them by reflecting on how users actually experience them."
"The only thing I know is that I know nothing." - Socrates | "The only thing I know is that users will always surprise me."
"You cannot step into the same river twice." - Heraclitus | "You cannot step into the same document twice - you always return armed with new knowledge."
"He who knows only his own side of the case knows little of that." - John Stuart Mill | "They who test only one user path knows little of the full workflow."
"The measure of intelligence is the ability to change." - Albert Einstein | "The measure of good documentation is the ability to adapt when your product or users do."
"Truth springs from argument among friends." - David Hume | "Clarity springs from review among teammates."
"We are what we repeatedly do. Excellence, then, is not an act but a habit." - Aristotle | "Those who do not document past issues are condemned to rediscover them."
"The more sand that has escaped from the hourglass of our life, the clearer we should see through it." - Niccolò Machiavellia | "The more versions a system has gone through, the clearer our documentation should become."