Notebook Is A Better Readme • Hacker News Board

Re: Notebook Is A Better Readme

#31

Post by SamBam » Sat, Dec 19, 2020, 2:30 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…

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

Re: Notebook Is A Better Readme

#32

Post by kvlr » Sat, Dec 19, 2020, 2:35 PM UTC

For our notebook format at Nextjournal we use an edn appendix to store metadata like results and environment (docker image). The user-edited content is just plain markdown, while also being runnable reproducibly. See [1] and run it at [2].

[1]: https://github.com/nextjournal/notebook-format-demo/blob/mas...

[2]: https://github.nextjournal.com/nextjournal/notebook-format-d...

Re: Notebook Is A Better Readme

#33

Post by arvindamirtaa » Sat, Dec 19, 2020, 2:35 PM UTC

Complicating READMEs may not be the best idea. This is under the assumption that README will be rendered in a full featured web browser which may not always be the case.

That said, I definitely see how this can become invaluable in documentation for DevOps tools.

Re: Notebook Is A Better Readme

#34

Post by maple3142 » Sat, Dec 19, 2020, 2:37 PM UTC

Although I think README need to be static, I still think that having some images clearly describe what is this project for or some code example is better. English is not my first language, so I don't like to read a wall of English text. Short paragraph with code example and images are much more approachable for me. This is also a reason why I rarely use manpage, and use "--help" or just Google it instead.

Re: Notebook Is A Better Readme

#35

Post by Grimm1 » Sat, Dec 19, 2020, 2:39 PM UTC

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.

Re: Notebook Is A Better Readme

#36

Post by qsort » Sat, Dec 19, 2020, 2:40 PM UTC

threatofrain wrote: post #24

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.

Readme files aren’t readme files anymore. Now they’re collaborative team documents used for all sorts of purposes, such as onramping new people or explaining bureaucratic structure. The times should reflect this evolving need.

Those things are deserving of being explained, but do they really need to be in a readme? Can't we just link to them?

Re: Notebook Is A Better Readme

#37

Post by enriquto » Sat, Dec 19, 2020, 2:44 PM UTC

globuous wrote: post #30

Org mode is a better readme and a better notebook :)

Is there a way to enjoy all the pleasures of org mode without having emacs installed on my computer?

If there isn't, it seems that "org mode" is a very bad name and it should be called simply "emacs". Or, if you want to be too precise, "emacs, with some configuration tweaks".

Re: Notebook Is A Better Readme

#38

Post by prepend » Sat, Dec 19, 2020, 2:52 PM UTC

threatofrain wrote: post #24

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.

Readme files aren’t readme files anymore. Now they’re collaborative team documents used for all sorts of purposes, such as onramping new people or explaining bureaucratic structure. The times should reflect this evolving need.

They can be both. I actually like markdown for collaborative team documents because they are so simple. I’d rather people focus on the content rather than trying to make the perfect PowerPoint or format a word doc or something.

I also like that the on-ramp document can get PRs from new hires who find some improvement, etc etc.

Re: Notebook Is A Better Readme

#39

Post by davb » Sat, Dec 19, 2020, 2:56 PM UTC

Scrolling on that site lags so badly on Chrome on Android (Pixel 4a).

Re: Notebook Is A Better Readme

#40

Post by bayindirh » Sat, Dec 19, 2020, 2:58 PM UTC

threatofrain wrote: post #24

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.

Readme files aren’t readme files anymore. Now they’re collaborative team documents used for all sorts of purposes, such as onramping new people or explaining bureaucratic structure. The times should reflect this evolving need.

> The times should reflect this evolving need.

There's no need since, these needs are already addressed in their own files for decades IMHO.

Readme files are a general map most of the time. Other relevant files are "Install", "Contributing", etc. Your README should be concise and refer to another text (or markdown) files in the repository.

Of course people adapt and evolve but, I don't understand the attitude of "We've just invented this". No, we didn't. README.1st, CONTRIBUTING files are as old as computing now.