24 ms·
A good readme is a lot like a good manpage: http://rtomayko.github.com/ronn/ http://rtomayko.github.com/ronn/
by adamv 16y ago
A good readme is a lot like a good manpage: http://rtomayko.github.com/ronn/ http://rtomayko.github.com/ronn/
- ekidd 16y agoI'm a huge fan of good man pages. A good man page contains a short overview, some detailed reference documentation, and (if you're lucky) some useful examples. A good README, on the other hand, explains why the accompanying program is useful, shows some examples of how to use it, and points the user towards detailed documentation. Now, perhaps the _ideal_ man page would also serve as a perfectly good README. But if you do a survey of merely _good_ manpages, and use them as a standard for writing READMEs, then you're probably going to get mediocre READMEs. Typical Unix and Linux manpages, even the good ones, don't spend enough time on high-level overviews and examples.