What Writing Dictionaries Taught Me about Writing Documentation
summary
Claim: a dictionary project becomes usable documentation when it pairs concise definitions with many real-world examples and lets users contribute. Evidence: Wordnik holds far more words than traditional dictionaries and runs an API with 20,000 registered users, which surfaces issues like forgotten API keys and drove clearer docs. Tools and outcomes: publishing swagger (OpenAPI) examples, adopting conversational tone, tolerating live mistakes, and encouraging playful contributions (limericks, bots) prove helpfulness beats asserted authority. Practical takeaway: show working exemplars, document exact inputs/outputs, and fix errors fast.
AI-written summary · about
chapters (9)
- 0:00Start
- 2:36How Dictionaries Are Made
- 10:28Free-Range Definitions
- 11:16Count the Number of Entries in a Dictionary
- 12:40Lexicographers Expertise
- 13:56People Hate Change
- 20:04Fear of Making Mistakes
- 23:29Code Patterns
- 25:09The Semicolon Appreciation Society
related talks
34mHumanizing Your Documentation
29mHumanizing Your Documentation
01h 24mWriting Documentation - Practices and Theory
25mWriting So Your Words Are Read
51mWriting the Darn Docs
23mKeynote: The Human API: Building Your Project's Second Source of Truth
29mHumanizing Your Documentation
37mHumanising Your Documentation