Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Notebook Is A Better Readme

matyunya-readme.ellx.app

Post reply on HN
Print view View original

11–20 of 79 posts

Re: Notebook Is A Better Readme

#11

Post by qayxc »

enriquto wrote: post #9

No. And, by the way, stop with the markdown README crazyness. README files are supposed to be readable as plain text and hard-wrapped at 80 columns. I have found some "readme.md" monstrosities with github-specific markdown that were unreadable outside the github website. This is akin to presenting your readme file as a flash ainmation.

Markdown is still just plain text without any "crazyness".

Stuff like "## Header" isn't any more "crazy" than the ASCII art used in many Readme's of old and on top of that doesn't rely on specific monospace fonts or fixed width. And more advanced stuff like hyperlinks or tables are hard to do "right" in text anyway, since it's basically meta data without an objective "right" or "wrong" way of representing it.

I also truly believe that it's time to finally let go of the 80-columns obsession. It's not 1975 anymore and even the ancient VT100 from 1978 had a 132-column mode. It's just an indefensible relic that held developers hostage for way too long.

Still want 80 columns on your 4k 27" 10bpp HDR monitor? Fine, but don't insist on others bending over backwards just not anger the grey beards on top of Mount Teletype... Text editors are perfectly capable of introducing proper line breaks even at word boundaries if need be.

It's really just become l'art pour l'art to force this arbitrary (by today's [and by today I mean the past 30 years!] standards) restriction on developers with no benefit to readability.

Re: Notebook Is A Better Readme

#12

Post by gostsamo »

ThinkBeat wrote: post #8

No. It might be useful for some but it would make it much harder for others I question Unicode as well. A readme file should work as expected in simple text editor. Like an early version of VI from 30 years ago. Anything fancy should be able in the documentation hierarchy for the project

Sorry, but utf-8 is necessary. The world is not USA and some of us exist outside of it, where ascii is gross disregard to conventions. I can agree on plain text readmes, but there is reason that the world moved away from english only encodings and if you want to stay thirty years in the past, this is your choice.

Re: Notebook Is A Better Readme

#13

Post by Archelaos »

gostsamo wrote: post #12
ThinkBeat wrote: post #8

No. It might be useful for some but it would make it much harder for others I question Unicode as well. A readme file should work as expected in simple text editor. Like an early version of VI from 30 years ago. Anything fancy should be able in the documentation hierarchy for the project

Sorry, but utf-8 is necessary. The world is not USA and some of us exist outside of it, where ascii is gross disregard to conventions. I can agree on plain text readmes, but there is reason that the world moved away from english only encodings and if you want to stay thirty years in the past, this is your choice.

This. Unicode is the new ASCII. One should avoid, of course, the fancy corners of Unicode (such as the private use area, emojis, hieroglyphs, etc.) unless specific to the use case. But the use of well established Unicode code pages in READMEs should be no problem for temporary text editors at all.

Re: Notebook Is A Better Readme

#15

Post by ktpsns »

prepend wrote: post #7

No, I don’t think so. Readme pages should be the lowest common denominator to information on the project no matter where you come across it. I think markdown is probably as fancy as it can get and still be readable in the terminal after I clone the repo, or any ide, or the browser. I think of it as a more formatted man page. Would I want a man page to be interactive? Or only work in a browser. I also think if GitHub…

This. Readme files should be readable by anyone. That's one of the promises in the filename (it is readable ;) ). There is a reason readme files are not PDF files.

Re: Notebook Is A Better Readme

#16

Post by enriquto »

qayxc wrote: post #11
enriquto wrote: post #9

No. And, by the way, stop with the markdown README crazyness. README files are supposed to be readable as plain text and hard-wrapped at 80 columns. I have found some "readme.md" monstrosities with github-specific markdown that were unreadable outside the github website. This is akin to presenting your readme file as a flash ainmation.

Markdown is still just plain text without any "crazyness". Stuff like "## Header" isn't any more "crazy" than the ASCII art used in many Readme's of old and on top of that doesn't rely on specific monospace fonts or fixed width. And more advanced stuff like hyperlinks or tables are hard to do "right" in text anyway, since it's basically meta data without an objective "right" or "wrong" way of representing it. I also…

I'm not against markdown per-se, but against markdown readme files that use so much markup (heh) that become unreadable as plain text, no matter your screen size.

> Still want 80 columns on your 4k 27" 10bpp HDR monitor?

This is offtopic, but a strong YES. There's good reason why on printed books you don't ever see more than about 70 characters per line of text. Long lines are just unreadable, regardless of your font/window/screen size.

Re: Notebook Is A Better Readme

#17

Post by qayxc »

enriquto wrote: post #16
qayxc wrote: post #11

Earlier quoted context omitted.

Markdown is still just plain text without any "crazyness". Stuff like "## Header" isn't any more "crazy" than the ASCII art used in many Readme's of old and on top of that doesn't rely on specific monospace fonts or fixed width. And more advanced stuff like hyperlinks or tables are hard to do "right" in text anyway, since it's basically meta data without an objective "right" or "wrong" way of representing it. I also…

I'm not against markdown per-se, but against markdown readme files that use so much markup (heh) that become unreadable as plain text, no matter your screen size. > Still want 80 columns on your 4k 27" 10bpp HDR monitor? This is offtopic, but a strong YES. There's good reason why on printed books you don't ever see more than about 70 characters per line of text. Long lines are just unreadable, regardless of your font…

> There's good reason why on printed books you don't ever see more than about 70 characters per line of text.

That reason is called format not readability, though.

Newspapers (if you still remember these) go way beyond this limit and are still readable.

Re: Notebook Is A Better Readme

#18

Post by DanBC »

qayxc wrote: post #17
enriquto wrote: post #16

Earlier quoted context omitted.

I'm not against markdown per-se, but against markdown readme files that use so much markup (heh) that become unreadable as plain text, no matter your screen size. > Still want 80 columns on your 4k 27" 10bpp HDR monitor? This is offtopic, but a strong YES. There's good reason why on printed books you don't ever see more than about 70 characters per line of text. Long lines are just unreadable, regardless of your font…

> There's good reason why on printed books you don't ever see more than about 70 characters per line of text. That reason is called format not readability, though. Newspapers (if you still remember these) go way beyond this limit and are still readable.

Don't newspapers use columns, and thus go way below this limit?

Re: Notebook Is A Better Readme

#20

Post by tclancy »

I think this is a commendable idea. It may be that conflating it with README is not the right idea, but I can definitely see value in having a playground/ sandbox. Most people commenting here are probably comfortable in code and getting things up and running locally, but that isn’t everyone or even most people. Being able to see the library do what you want gives newer users far more incentive to stick with the possibly painful process of making it work for them in development.
Post reply on HN