41–50 of 79 posts
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.
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…
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.
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.
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.
I would love if every package had a LINK to a live notebook to test things, but it should not replace the README.
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".
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.
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…
That's what Stallman wanted for GNU. The results speak for themselves.
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".
It's as much "emacs with some configuration tweaks" as VS Code is "chromium, with slightly improved ".
W.r.t. the good question in a comment that definitely has more than just that, yes, there are partial ports of Org mode to vim, VS Cod{e,ium}, and AFAIK Sublime Text, but Org does make use of some facilities of Emacs that are not as easy to replicate on these editors. For exporting, Pandoc can help to some extent, but it's imperfect and not as configurable.
Oh god please no. The last thing we need is more dependance on web browsers.
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.