Notebook Is A Better Readme
matyunya-readme.ellx.app
Notebook Is A Better Readme
1–10 of 79 posts
Re: Notebook Is A Better Readme
#2One thing that would have helped me as a reader is to cite the name Ellx by adding the bracket text in this sentence:
> 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.
Re: Notebook Is A Better Readme
#3One thing that would have helped me as a reader is to cite the name Ellx by adding the bracket text in this sentence: > 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.
Thank you, I added reference to the docs:
Re: Notebook Is A Better Readme
#4A while ago I made a demo of an “interactive readme” for a fuzzy string matching library called fuzzyset: http://glench.github.io/fuzzyset.js/ui/
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.
Re: Notebook Is A Better Readme
#5Oh god please no. The last thing we need is more dependance on web browsers.
Re: Notebook Is A Better Readme
#6I 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.
Re: Notebook Is A Better Readme
#7No, 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.
Re: Notebook Is A Better Readme
#8No. 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
Re: Notebook Is A Better Readme
#9No.
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.
Re: Notebook Is A Better Readme
#10What 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.