Notebook Is A Better Readme • Hacker News Board

Re: Notebook Is A Better Readme

#61

Post by gostsamo » Sat, Dec 19, 2020, 8:26 PM UTC

ThinkBeat wrote: post #28

gostsamo wrote: post #12

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…

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.

Re: Notebook Is A Better Readme

#62

Post by what2build » Sat, Dec 19, 2020, 9:11 PM UTC

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…

Make a blog post. Social media is for cats and shallow memes.

I too prefer to subjectively dictate based upon prior experience.

How someone organizes a project is up to them, and the folks interested in it?

Re: Notebook Is A Better Readme

#63

Post by ThinkBeat » Sat, Dec 19, 2020, 9:24 PM UTC

gostsamo wrote: post #61

ThinkBeat wrote: post #28

Earlier quoted context omitted.

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…

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 are many close editors today that do not support full unicode

Presumably advocating unicode should not discriminate against languages with Arabic.

Most code editors can not do that right out of the box. More and more can.

Re: Notebook Is A Better Readme

#64

Post by einpoklum » Sat, Dec 19, 2020, 9:42 PM UTC

bxparks wrote: post #46

Somewhat of a tangential comment: I love that README files have become useful again, say, in the last 10 years. I think GitHub and the proliferation of open source projects may have had something to do with that. My memory is a bit fuzzy, but back in the late 1980s and most of 1990s, the README file was useful,and it was the first thing that I opened when I downloaded a software package. Then sometime in the 2000s, t…

> I love that README files have become useful again, say, in the last 10 years.

They have always been extremely useful, actually. It is always the first thing you open when you download a package (well, that or INSTALL). You're right that the README's of, say, MS-Windows or such software is less useful, but I don't know that this situation has improved recently. Perhaps it's just your use of FOSS? :-)

Re: Notebook Is A Better Readme

#65

Post by einpoklum » Sat, Dec 19, 2020, 9:46 PM UTC

wruza wrote: post #10

What we should do is turn readmes into readmes and not into documentation. Github-like readmes are awful for that purpose. They have no TOC, heading styles are often misleading after two levels, and there is no indenting that could help. For contrast, GTK documentation is great, and so are G docs in general. It usually has toc, intro, description, examples and then detailed and cross-referenced “what you pass and wha…

> Github-like readmes are awful for that purpose. They have no TOC

I add TOCs in README.md's as they get longer, and I suggest everyone consider doing the same.

Example:

https://github.com/eyalroz/tpch-dbgen

Re: Notebook Is A Better Readme

#66

Post by bitwize » Sat, Dec 19, 2020, 9:53 PM UTC

Yeah, how about no. READMEs should be viewable in anything and NOT run any code. There is a time and a place for documentation which exhibits the features of the thing being documented inline with the text, but the README is not it. Tell me what the thing is and does and where to get more info.

Re: Notebook Is A Better Readme

#67

Post by prepend » Sat, Dec 19, 2020, 9:59 PM UTC

pietrovismara wrote: post #53

ktpsns wrote: post #15

Earlier quoted context omitted.

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.

Ok but then you get README files that are useless on their own, containing basically only a brief descriptions and several links to github pages / docs website. What good does it make to be able to read that on your terminal?

I don’t think thats required and based on viewing probably dozens of readmes a week that’s pretty rare. It varies a lot by project but I find readmes pretty useful even if they do point to a readthedocs site for more info.

I think it’s unusual to have a readme with as much info as a man page, but readme is for the source right. The documentation is usually organized depending on the type of project.

Re: Notebook Is A Better Readme

#68

Post by whereistimbo » Sat, Dec 19, 2020, 10:22 PM UTC

znpy wrote: post #5

Oh god please no. The last thing we need is more dependance on web browsers.

IPython cell can run in terminal too. Jupyter notebook consist of JSON too, just waiting for someone who could combine all of these things in terminal.

Re: Notebook Is A Better Readme

#69

Post by contingencies » Sat, Dec 19, 2020, 11:03 PM UTC

Grimm1 wrote: post #35

Perhaps we need to adopt something like a "TRYME" as a standard way for people who want to sample a project or do a little interactive learning with it.

An examples/ subdirectory seems a semi-frequent open source solution to this.

Re: Notebook Is A Better Readme

#70

Post by [deleted] » Sat, Dec 19, 2020, 11:05 PM UTC

cyberdelica wrote: post #21

There is already a better readme. It's called a man page. The original "online" documentation. The ability to have content generated dynamically, using source and system operators. Spreadsheet style abilities with a touch of awk. Perhaps it needs to be rebranded with a vegetable name, for modern developers to take interest. Samphire, maybe.

[deleted]