README 80 character limit or just let the users editor handle it?

Question

I am sure a lot of people will argue both ways and unfortunately there seems to be no 'official answer'. Part of my just wants to write and not pay any attention to this seemingly insignificant detail but I am curious how does the SO community feel about one option over the other? If you have an opinion state it and give supporting reasons. I am pretty sure vim has a setting buried in it to help me out here so I can have the best of both worlds.

My vote is to just type paragraphs until my eyes bleed and let the wrapping occur as it will because it frees me from having to format the text with each and every edit in the middle of the text.

Answer 1

Write it without worrying about the formatting, but then format it. Formatting as you go is likely to create more stilted text as you interrupt your own train of thought - but not formatting at all is doing your users a disservice.

Don't forget that the README may very well be the very first impression that the user gets of your software - and you know what they say about first impressions. I get very frustrated by READMEs which display really badly, or make me scroll.

In particular, if you're writing documentation for a Windows-based project, try opening the README in Notepad - because that's what many users will have as the default to open text files.

(There's then the issue of what kind of line-ending you should use for a multi-platform project - I've seen projects have README.windows and README.linux etc, which works well but takes a lot of effort to maintain.)

Finally, remember that if your project is popular, a lot more time will be spent reading the README than writing it. If it takes you 5 minutes to format it afterwards, but you have 500 people reading it, then you've effectively "spent" less than a second per user - for a potentially significant benefit. Show you care :)

Answer 2

Vote for fixed width readme

I work in a number of different environments at the same time (Widescreen monitor using TextMate, 13" Laptop with Eclipse, the Commandline everywhere). I also use varied popin devices, too. Mac Mice have the sidescroll built in. Most other mice do not. So the means to sidescroll a line may not exist.

I have come to favor a stricter line length. In code, READMEs etc. I feel that a line length any longer than 100ish chars will absolutely destroy my ability to read something, particularly if I do not have the means to manage it. Since you can't be sure what your reader will be using, it's probably best to go with shorter, easier to read line lengths.

Answer 3

According to your avatar, you're using Vim, so I'll suggest that formatoptions=+w in Vim is your friend. It uses "flowed text" and saves you lots of trouble when it's time to reformat. Wrapped lines are terminated with a space, this way you avoid unwanted reformatting of lines. When it's time to save, enter "gggqG" to reformat the whole file. I've used formatoptions=tcqw for many years and I'm completely satisfied with it.

Answer 4

More than 80 characters and it's a bitch to read when you only have an 80 character terminal.

This may sound like a message from the past, but when do you really need to be able to read the docs? When everything is messed up and you can't get your window system up and running.

Don't kick people when they're down, use 80 character as a hard limit.

There is no need to have a wider limit. It's easier to read columns that aren't too wide. There is a reason newspapers don't write lines that span the whole newspaper (that would be unreadable). The alternative then would be to trust the users viewer to auto-wrap it. In practice I've found that to be a pain, in Linux (more, less, harder to grep, emacs, vim) and in Windows notepad (I have to go through menus to enable auto-wrap for example).

For these reasons I say 80 characters or less, please.

Answer 5

Provide a text-only readme which can be easily read on every kind of PC configurations, and for which you can imagine all sorts of difficulties in opening and reading it. But also provide a nicely formatted PDF version for users who might actually want to read something.