Re:Notebook Is A Better Readme
by jeroenhd on Saturday December 19, 2020 @10:40AM
(#25478033)
I'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.
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.