Kim Crayton - SeattleJS Conference 2017
summary
Argues documentation must be split for three audiences—intro/newbies, experienced users, and contributors—and starts with a one-paragraph abstract that states what the project does, dependencies, and known install pain (example: Ruby took two weeks). Recommends a 3-step quickstart, searchable living docs updated on every merge (or by a bot), a contributor guide with code of conduct and merge process, defined terms/style guide, accessibility notes, and flagging beginner-friendly issues like “good first issue.”
AI-written summary · about
chapters (13)
- 0:00Introduction and speaker intro
- 1:47Why docs matter for new users
- 3:54Keep docs simple and inclusive
- 6:30Docs as living documents
- 9:02Reader perspective and problem solving
- 12:15Types of documentation needed
- 14:22Creating an abstract for clarity
- 16:54Step-by-step setup instructions
- 18:41Updating docs with every change
- 20:08Building contributor community
- 21:35Code of conduct and consequences
- 23:21Flagging newbie-friendly issues
- 24:45Documentation as storytelling
related talks
48mBeyond Words: Crafting User-Friendly Documentation
33mWhat The Doc?!?! How to Write and Read Documentation That Allows You To Get Sh*t Done!
28mImproving Your Documentation: A talk for developers who want to write stuff good
56mEffective Documentation: The Key to Open Source Growth
51mTechnically speaking improve your code documentation
45mDocs or it didn't happen!
52mTechnically Speaking: improve your code with documentation
49mExplain Yourself! Documentation for Better Code