Fork the current README off into DOCS and write a real README
ddalcino opened this issue · comments
Here's a hot take: Our current README isn't a README at all, it's a manual!
I feel personally responsible for this problem, since I wrote an early draft of the README, and the only thing I wrote was a tutorial.
There are lots of competing opinions on what should go into a README (it's worth a quick google), but none of them say that your README should just be a manual. Here's an opinion on READMEs from https://liw.fi/readme-review/ that I find particularly helpful:
- A README is meant for someone who is first encountering the project to be able to quickly decide if they want to learn more about it.
- A README should have a “blurb”: a very short, dense summary of the project aimed at someone who doesn’t know anything about it yet and may not know the topic area.
- A README is not the manual, but it may have an example of how to typically use the software, especially if that helps the reader understand the software better.
- A README should say how the copyright and other legal aspects affect the project. It should say what copyright licenses the project uses.
- A README can also contain instructions for installing the software, or how to run its test suite, and other practical aspects, but those can go into other documentation as well. Referring to them is good, as is linking to more information about the project, and who works on the software.
I think we desperately need a "blurb" that contains some very clearly stated goals of the project; I think it would help us cut down on issues/PRs that are tangent to our goals. Here's a summary of what I think the project is about:
- This is a batteries-included quick-start to building programs (and/or libraries?) in C++. Everything in the project is meant to get you to follow best-practices while writing C++ code, without having to stop and write a bunch of boilerplate CMake.
- This project is mostly about "Use the tools available". To that end, the project:
- pushes you towards using Conan for dependency management, so you don't have to reinvent the wheel, and you have an easy means of getting your dependencies to all of your teammates.
- lowers the barrier of entry to using unit tests, continuous integration, and code coverage, so you can always measure what's broken and what isn't.
- gives you access to static analyzers and sanitizers, which you can activate as simply as flipping a switch.
- gives you a quick-start to using several GUI libraries, which can be tricky to set up in a CMake project.
- This project is not about CMake best-practices. It attempts to employ the best CMake code that it can, but when given the choice, it will always sacrifice CMake best-practices to push you towards good C++ tools and C++ best-practices (see #123).
I am certainly wrong about some of these goals, and I'm surely missing something; please correct me! I sure hope I'm wrong about the CMake best-practices thing; it would be nice to follow both C++ and CMake best practices.