X.4 · Capability in Cross-cutting

Communication

Explaining ideas clearly in writing and speech, to technical and non-technical audiences.

Map4 skills

Not startedLearningComfortable

4 skillsClick a hexagon to set your status

X.4.1Technical writing and documentationClear, accurate writing about technical things.
X.4.2Product narrativesTelling the story of a product, a problem or a decision.
X.4.3Clear explanationsExplaining complex things simply without losing accuracy.
X.4.4Persuasive argumentsMaking a case that changes minds, with evidence and empathy.

Mark all 4

Where to start

3 resources

courseStart here
Technical writing one ↗
Google for Developers · free course
Google's free course for engineers on clear sentences, lists, paragraphs and audience.
articleStart here
Write simply ↗
Paul Graham · 2 min
Plain words reach more readers and expose weak ideas, a two-minute argument for simple prose.
articleStart here
Design docs at Google ↗
Malte Ubl · 2020 · 21 min
How a short document with goals, non-goals and alternatives considered makes trade-offs explicit before code.

2 tools

ToolOpen source
Vale
vale.sh ↗
Prose linter that checks docs against a style guide, in the editor or in CI.
ToolFreemium
Hemingway Editor
hemingwayapp.com ↗
Highlights long sentences, passive voice and complex words as you write.