Live data from Hacker News

Notebook Is A Better Readme

matyunya-readme.ellx.app

71–79 of 79 posts

Re: Notebook Is A Better Readme

#71
Okay, um, a readme file is just the lowest common denominator “what the heck is in this directory tree” file. Something to get your bearings from. Something that can then point to some more fancy documentation like a homepage.

But now I guess it’s a landing page with a bunch of tags at the start. That’s not a good development in my opinion.

Re: Notebook Is A Better Readme

#72

Earlier quoted context omitted.

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.

I am unsure why the hostility is needed. I am also unclear on the incorrect assumptions you made about me. I do not live in America and the country I live in has it's own set of special characters to deal with. I can perhaps agree that American cultural imperialism in computer science as with many other fields This post was primarily directed at GitHub. It has users from all over the world. Having a common Lingua fra…

> I do not live in America and the country I live in has it's own set of special characters to deal with.

Yes. I’ve noticed that programmers from all over the world are narrow-minded and view things like international, inclusive standards to be “bloat”, preferring a monoculture since that would make things simpler (technically simpler, which is all that matters if you have no sense of aesthetics or culture).

Re: Notebook Is A Better Readme

#73

Earlier quoted context omitted.

You said that you question utf-8. I do not. That's it. It is not about imperialism, but computer science is not all about problems that could be expressed in english either. What I'm supposed to do if I need to write a program for manipulating cyrillic texts? Transcribe everything in latin? Be serious and imagine that though english is useful, it is not sufficient.

The contexts remains ReadMe files on Github. Remember that. If you wish to write a program to do Y then write the code your tests etc using whatever encoding makes you happy. Nowhere have I said no Unicodein any repositories which is the strawman you are reachinging for. You can still write Readme files without Unicode so that the great majority of user of public Github can see what your project is about. Now there a…

> the great majority of use

The great majority of users has editors that can handle unicode. What editor common today doesn't do UTF-8?

Re: Notebook Is A Better Readme

#75

Earlier quoted context omitted.

You said that you question utf-8. I do not. That's it. It is not about imperialism, but computer science is not all about problems that could be expressed in english either. What I'm supposed to do if I need to write a program for manipulating cyrillic texts? Transcribe everything in latin? Be serious and imagine that though english is useful, it is not sufficient.

The contexts remains ReadMe files on Github. Remember that. If you wish to write a program to do Y then write the code your tests etc using whatever encoding makes you happy. Nowhere have I said no Unicodein any repositories which is the strawman you are reachinging for. You can still write Readme files without Unicode so that the great majority of user of public Github can see what your project is about. Now there a…

Let's imagine that I'm writing a cyrillic program. The users are most likely not english, the stakeholders are not english, the examples that the program works with are not ascii. Yet, you insist that in the readme I'm not using anything cyrillic related and use ascii instead.

If I happen to find an arabic readme, then I'll know that either I'm not the target audience, or that the author does not know english and might loose my contributions. Neither of those gives me the right to open a PR and insist that the readme is adjusted for my use case only and degrades the user experience of others.

What I strongly disagree with you is that from the principal of "be conservative in what you send and liberal in what you accept" you choose to take only the first part and forget the latter. Ascii is nice when it is applicable for the use case, but it is not universally applicable and assuming so should be a personal mistake, not tax on everyone. Maybe the disagreement between us is in how we define target audience. You imagine that if it is published in Github, then it must be readable to anyone there. I think that if the project is ment to help certain type of people, then it it must be optimized for them, not for people who would never bother using it anyways.

Re: Notebook Is A Better Readme

#76
post #27
post #17

Earlier quoted context omitted.

> 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.

They go beyond the limit by displaying text in columns. Imagine how difficult it would be to read a broadsheet newspaper if the text ran from one edge of the page to the other. As lines get longer, it is increasingly difficult to find the starting point of the next line and reading speed and comprehension are reduced. https://www.sciencedirect.com/science/article/abs/pii/S10715...

Just for shits and giggles I grabbed a random book from the shelf and counted characters per column.

The book I grabbed was "Spoken Language Processing", Huang Acero, Hon (ISBN 0-13-022616-5) and I counted 88 characters per line. The book is still very readable, despite exceeding the claimed 70-odd character limit for books/columns. Another book sitting next to it (a numerical mathematics textbook) had 82 characters per line.

Granted, the limit of no more than 70 characters per line applies if whitespace and punctuation aren't counted, but that's never done with hard limits in digital documents either, so...

Re: Notebook Is A Better Readme

#77
post #44

Scrolling this page on mobile is terrible and I think that's a pretty compelling argument against it. I would love if every package had a LINK to a live notebook to test things, but it should not replace the README.

Thank you for pointing out the lag, it should be gone now.

Re: Notebook Is A Better Readme

#79
post #31
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…

Among the other issues mentioned, I also found basic scrolling on that page extremely slow on mobile.

Should be fixed now. Thanks for spotting this
Post reply on HN