6 ms·
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 i
by prepend 6y ago
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.
- ktpsns 6y agoThis. 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.
- sokoloff 6y agoIn the examples provided, I find the original text quite readable in text-only format. It just has additional richness if interpreted in notebook form. (I'm sure that someone will take the examples quite a bit farther and make portions of the documentation less accessible in plain utf-8 format, but major portions will still be entirely usable I think.) Are man pages not readable because the original source form is troff?
- threatofrain 6y agoReadme 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.
- qsort 6y agoThose things are deserving of being explained, but do they really need to be in a readme? Can't we just link to them?
- prepend 6y agoThey 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.
- bayindirh 6y ago> 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.
- jeroenhd 6y agoI'd say that after the launch of Github wikis/Pages, using READMEs as anything but a quick project overview is a regression rather than an evolution. Sure, you can put a bunch of quick links in there to get people started, but as a potential user interested in using a project, I'm not interested in your complete overview of the source code architecture or the necessary onboarding steps. Put a quick link in the README to guide people to the right place, but don't put all of your project documentation in there unless your project is particularly small. We've grown beyond storing a bunch of texts files in a SVN respository, every major source control system also has a way to document your project. If you choose to keep your documentation inside of your source control, the rise of Markdown viewers that support navigating links can help you achieve the same benefits by just linking to docs/project-overview.md in the top of your README.
- pietrovismara 6y agoOk 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?
- prepend 6y agoI 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.
- Frost1x 6y ago>Or only work in a browser. 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
- SamBam 6y agoAmong the other issues mentioned, I also found basic scrolling on that page extremely slow on mobile.
- dmaevsky 6y agoShould be fixed now. Thanks for spotting this
- dalbasal 6y agoDivergent goals, divergent choices. 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 6y ago> Would I want a man page to be interactive? Or only work in a browser. That's what Stallman wanted for GNU. The results speak for themselves.
- what2build 6y agoMake 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?