Comments on: Things your ReadMe must include http://boredzo.org/blog/archives/2008-05-20/things-your-readme-must-include The personal weblog of Peter Hosey. Tue, 07 Oct 2008 18:25:37 +0000 http://wordpress.org/?v=2.5.1 By: Jesper http://boredzo.org/blog/archives/2008-05-20/things-your-readme-must-include#comment-204744 Jesper Sun, 22 Jun 2008 10:05:18 +0000 http://boredzo.org/blog/?p=672#comment-204744 CS: That's ridiculous. A readme should be designed to be read quickly on screen during installation or usage. PDF delivers something that's paged and more of an inconvenience to scroll through, unless you're deft enough to enable "continuous" PDF display in Preview. Anyone can deliver a perfectly charming HTML-formatted readme, if formatting is of any particular importance here, and I argue that it shouldn't be. A readme should be as stripped-down as possible, even devoid of branding beyond your company/label's name in text (not a logo!) and your application's icon, so that nothing distracts you from the actual text. It's not called a lookatme, and it's not a good place to stun your audience with a coherent graphical profile or visual eloquence. I'm not opposed to such things, quite the opposite, but they have no place in a readme. CS: That's ridiculous. A readme should be designed to be read quickly on screen during installation or usage. PDF delivers something that's paged and more of an inconvenience to scroll through, unless you're deft enough to enable "continuous" PDF display in Preview. Anyone can deliver a perfectly charming HTML-formatted readme, if formatting is of any particular importance here, and I argue that it shouldn't be.

A readme should be as stripped-down as possible, even devoid of branding beyond your company/label's name in text (not a logo!) and your application's icon, so that nothing distracts you from the actual text. It's not called a lookatme, and it's not a good place to stun your audience with a coherent graphical profile or visual eloquence. I'm not opposed to such things, quite the opposite, but they have no place in a readme.

]]> By: rentzsch http://boredzo.org/blog/archives/2008-05-20/things-your-readme-must-include#comment-199537 rentzsch Mon, 26 May 2008 04:19:35 +0000 http://boredzo.org/blog/?p=672#comment-199537 Tonya Engst wrote a series of articles a while back for TidBITS. A bit dated now, but still good reading: http://db.tidbits.com/series/1039 Tonya Engst wrote a series of articles a while back for TidBITS. A bit dated now, but still good reading:

http://db.tidbits.com/series/1039

]]> By: CS http://boredzo.org/blog/archives/2008-05-20/things-your-readme-must-include#comment-199300 CS Sun, 25 May 2008 06:07:31 +0000 http://boredzo.org/blog/?p=672#comment-199300 Fine guidelines, but I'd disagree about PDF. It's very common to distribute documents in PDF these days, and every MacOS X user has a perfectly good PDF viewer in the form of Preview. A nice thing about PDF (indeed, the entire point of the format) is that users see the document exactly the way the author created it, and that may be important to some authors. I agree that if the user needs to print your ReadMe, you've got trouble. Nevertheless, an author may want his or her ReadMe to look a certain way, perhaps to match the appearance of other documentation, or so that the ReadMe can do double-duty as an easily printable promotional brochure. Fine guidelines, but I'd disagree about PDF. It's very common to distribute documents in PDF these days, and every MacOS X user has a perfectly good PDF viewer in the form of Preview. A nice thing about PDF (indeed, the entire point of the format) is that users see the document exactly the way the author created it, and that may be important to some authors.

I agree that if the user needs to print your ReadMe, you've got trouble. Nevertheless, an author may want his or her ReadMe to look a certain way, perhaps to match the appearance of other documentation, or so that the ReadMe can do double-duty as an easily printable promotional brochure.

]]> By: Wes http://boredzo.org/blog/archives/2008-05-20/things-your-readme-must-include#comment-197432 Wes Wed, 21 May 2008 01:32:49 +0000 http://boredzo.org/blog/?p=672#comment-197432 Handy little post. I'll keep it in mind next time I'm writing a README. Handy little post. I'll keep it in mind next time I'm writing a README.

]]> By: ssp http://boredzo.org/blog/archives/2008-05-20/things-your-readme-must-include#comment-197145 ssp Tue, 20 May 2008 11:01:26 +0000 http://boredzo.org/blog/?p=672#comment-197145 I'd also say an easily findable e-mail address in the read me will leave a good impression. Why should the user have to click through a website and try to find contact info there? I'd also say an easily findable e-mail address in the read me will leave a good impression.

Why should the user have to click through a website and try to find contact info there?

]]>