Ten Steps to a Better README
summary
Search finds 300,000 “just read the code” results and argues READMEs must state a concrete claim and make it usable: list prerequisites and build steps (make, Maven, even Fortran compilers), provide an ./install script to reach hello world quickly, show where to put data and which configs to edit, put the problem and top actions first, use clear bullets, include a troubleshooting list, a contribution section and a chosen license and changelog so users can decide when to upgrade.
AI-written summary · about
chapters (18)
- 0:00Start
- 0:40READMES: A Helping Hand
- 0:57Ten Steps to a Better README
- 1:12Inspiration
- 1:28Attitude: Sheldon or Austen
- 1:44Software: Need / Solution
- 2:03Short, Declarative Sentences
- 2:20Prerequisites
- 2:34Build that Software
- 2:47How Do I Install It?
- 3:05Is the Software Ready?
- 3:20Tips and Tricks
- 3:34Tips People Sean Documentation
- 3:52Avoiding Walls of Text
- 4:10Troubleshooting
- 4:23Contributions
- 4:46Licensing and Credits
- 5:14READMEs With Attitude
related talks
23mWrite the Readable README
22mWrite Prose, Not just programs
48mBeyond Words: Crafting User-Friendly Documentation
49mExplain Yourself! Documentation for Better Code
51mTechnically speaking improve your code documentation
28mImproving Your Documentation: A talk for developers who want to write stuff good
33mWhat The Doc?!?! How to Write and Read Documentation That Allows You To Get Sh*t Done!
20mStop writing docs; Start helping