7 ms·
One nice thing about GitHub and Bitbucket's focus on the project's README is that more software projects are providing a good, instantly-readable summary of the
by LeafStorm 15y ago
One nice thing about GitHub and Bitbucket's focus on the project's README is that more software projects are providing a good, instantly-readable summary of their project in the README instead of making you have to go elsewhere to find out what it's all about and how to get started.
One not-so-nice thing about GitHub and Bitbucket's focus on the project's README is that I have noticed several projects that dump all their project's documentation into the README and the examples instead of having proper narrative and API documentation.
- ricardobeat 15y agoI prefer all-encompassing READMEs over incomplete scattered documentation.
- stock_toaster 15y agoI think all-in-one-README works well for some things, but some of our projects at work would result in HUUUGE readme files. Not so pleasant if those were a single file. We have started using gollum-site[1] for our stuff that grows beyond a medium size length. The single-long-readme length issue appears to be alleviated by the nav construction in documentup though. Pretty slick. https://github.com/dreverri/gollum-site https://github.com/dreverri/gollum-site
- code_pockets 15y agoAgreed, though I'm guilty as charged. This has led me to re-think the README/documentation problem, and gave me an app idea. A little web app that allows the user to build a proper README with a template. Sort of those build a resume apps, but for README files. I plan on building it at the end of February, after I ship my current foss project.