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, the corporate lawyers took over the README file and it just became a wall of CAPITALIZED legal text that contained zero useful information. I stopped opening the README files. Then sometime in the 2010s, the README files became useful again, and I started to read them again. Not exactly sure when that happened.
> 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? :-)
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 allowed more flexible markdown (like allowing html and js) it would turn more into a MySpace chaos. I don’t think authors would limit themselves to nice functions only once you let the JavaScript and CSS cat out of the bag.
I think your example is neat but that’s what pages is for. Use pages and add a link at the top of your readme. Just because GitHub is the first thing your users see doesn’t mean it has to be. Make a project web site, direct users there. Use GitHub pages for that if you don’t have a site elsewhere.
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.
I think the disagreement largely boiks down to semantics of the word "readme." Both versions can coexist, probably will. They're just going argue about which one is the "real" readme... the old school or the one that the author wants you to read.
Shouldn't everything only work in a web browser? I'm not sure why documentation hasn't been migrated to containerized microservices deployed on K8s with a React frontend yet. This stuff is all sooo antiquated. /s
I think READMEs should be kept as simple as possible. They should remain compatible/functional with terminal output, and they shouldn't have dependencies.
But I also think many READMEs could be improved with the inclusion of a figure or two.
It really helps if the artefact has some kind of visual output, and if there isn't, some kind of diagram could be useful.
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 what you get back, and how errors are structured” and formatting to grasp it quickly. Compared to that, usual github docs are just unreadable crap with a little knowledge spread on paragraphs of spoken text.
Web browsers are an operating system these days. Having more dependence on them is like having more dependence on Linux/Windows/OSX. It's a pipedream to think they will remain consistent and/or shrink in use case.
Like it or not, this is here to stay. What we should fight against, imo, is not browsers as an idea - but the lack of diversity. We're in a reality where we all but only two/three browsers - it would be as if we only had Windows and OSX. The answer wouldn't be to get rid of Windows or OSX, but rather create a rich ecosystem of complementing operating systems - ala Linux.
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.
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.
Really cool that this author is thinking about ways to make that kind of stuff a reality. To me it’s exciting to imagine a future where programs automatically generate UIs that explain what they do with the best techniques from pedagogy, graphic design, video game mechanics, etc.
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.
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.
I prefer my readmes in plain text formats, be it Markdown, AsciiDoc, or unstructured txt.
This reminds me of two interesting projects, maid[0], a task runner that uses markdown files, and mandown[1], a markdown pager that improves reading markdown files in the terminal.
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".
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.
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].
This is not a new concept. Let's take a look at TensorFlow website, the site is basically Colab notebooks. Colab being free and requiring just a gmail account allows people to easily just run TensorFlow examples within seconds. This a specific case for Python, (other projects such as Pytorch, Google Cloud documentation, Beam follow the same patterns). When your README wants to show users runnable code or quick starts in my experience that's what user ultimately and if you can achieve this, people will actually use the README. From maintenance perspective, your README notebook may not be runnable in all Notebook environments which may be ok if user at least can render the content.
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.
I think it's funny that since I had js disabled all I saw was "Error - blah blah blah" and I thought this was arguing AGAINST using a notebook as a readme.
Looking at umatrix all the js is coming from a CDN too. I think it show the obvious benefit of readmes compared to a notebook which might be useless in 10 years due to link rot or the CDN going under.
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.
[+] [-] bxparks|5 years ago|reply
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, the corporate lawyers took over the README file and it just became a wall of CAPITALIZED legal text that contained zero useful information. I stopped opening the README files. Then sometime in the 2010s, the README files became useful again, and I started to read them again. Not exactly sure when that happened.
[+] [-] einpoklum|5 years ago|reply
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? :-)
[+] [-] prepend|5 years ago|reply
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 allowed more flexible markdown (like allowing html and js) it would turn more into a MySpace chaos. I don’t think authors would limit themselves to nice functions only once you let the JavaScript and CSS cat out of the bag.
I think your example is neat but that’s what pages is for. Use pages and add a link at the top of your readme. Just because GitHub is the first thing your users see doesn’t mean it has to be. Make a project web site, direct users there. Use GitHub pages for that if you don’t have a site elsewhere.
[+] [-] ktpsns|5 years ago|reply
[+] [-] dalbasal|5 years ago|reply
I think the disagreement largely boiks down to semantics of the word "readme." Both versions can coexist, probably will. They're just going argue about which one is the "real" readme... the old school or the one that the author wants you to read.
[+] [-] kps|5 years ago|reply
That's what Stallman wanted for GNU. The results speak for themselves.
[+] [-] SamBam|5 years ago|reply
[+] [-] what2build|5 years ago|reply
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?
[+] [-] Frost1x|5 years ago|reply
Shouldn't everything only work in a web browser? I'm not sure why documentation hasn't been migrated to containerized microservices deployed on K8s with a React frontend yet. This stuff is all sooo antiquated. /s
[+] [-] kowlo|5 years ago|reply
But I also think many READMEs could be improved with the inclusion of a figure or two.
It really helps if the artefact has some kind of visual output, and if there isn't, some kind of diagram could be useful.
[+] [-] wruza|5 years ago|reply
https://developer.gnome.org/gtk3/stable/GtkWindow.html
[+] [-] einpoklum|5 years ago|reply
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
[+] [-] znpy|5 years ago|reply
[+] [-] adkadskhj|5 years ago|reply
Like it or not, this is here to stay. What we should fight against, imo, is not browsers as an idea - but the lack of diversity. We're in a reality where we all but only two/three browsers - it would be as if we only had Windows and OSX. The answer wouldn't be to get rid of Windows or OSX, but rather create a rich ecosystem of complementing operating systems - ala Linux.
[+] [-] whereistimbo|5 years ago|reply
[+] [-] maple3142|5 years ago|reply
[+] [-] Glench|5 years ago|reply
Really cool that this author is thinking about ways to make that kind of stuff a reality. To me it’s exciting to imagine a future where programs automatically generate UIs that explain what they do with the best techniques from pedagogy, graphic design, video game mechanics, etc.
[+] [-] cyberdelica|5 years ago|reply
Perhaps it needs to be rebranded with a vegetable name, for modern developers to take interest. Samphire, maybe.
[+] [-] unknown|5 years ago|reply
[deleted]
[+] [-] Grimm1|5 years ago|reply
[+] [-] contingencies|5 years ago|reply
[+] [-] dummy_physicist|5 years ago|reply
[0]: https://github.com/egoist/maid
[1]: https://github.com/Titor8115/mandown
[+] [-] EduardLev|5 years ago|reply
Would be grateful if anyone could explain the significant differences between the two.
[+] [-] globuous|5 years ago|reply
[+] [-] enriquto|5 years ago|reply
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".
[+] [-] Privacy846|5 years ago|reply
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.
[+] [-] kvlr|5 years ago|reply
[1]: https://github.com/nextjournal/notebook-format-demo/blob/mas...
[2]: https://github.nextjournal.com/nextjournal/notebook-format-d...
[+] [-] spicyramen|5 years ago|reply
[+] [-] jariel|5 years ago|reply
The way github structures their doc trees is also not nice for easy navigation, which is required often for docs when they are structured that way.
[+] [-] tclancy|5 years ago|reply
[+] [-] vadansky|5 years ago|reply
Looking at umatrix all the js is coming from a CDN too. I think it show the obvious benefit of readmes compared to a notebook which might be useless in 10 years due to link rot or the CDN going under.
[+] [-] bitwize|5 years ago|reply
[+] [-] sokoloff|5 years ago|reply
> Now, I've been working on [Ellx, ]a tool
The first reference to the name that I saw was in relation to a scope convention and I had to go search for the anchor to that reference.
[+] [-] matyunya|5 years ago|reply
https://docs.ellx.app/#namespaces