Exemplar’s README.md file is 398 lines of Markdown. I think this runs the risk of overwhelming new users, and this is becoming more important as more projects start copying it. Does anyone have opinions on what we can omit from here?
Excellent point. And, you want opinions – you betcha I got those 
On a more serious note I’ve been working in all the repos and there’s massive readme divergence already. With optional and some others for example it has licensing info – maybe the license.md file didn’t exist when these were created? Many repos aren’t even close on this…
But back to examplar readme – the dependencies and development stuff isn’t actually well written and is a ‘do not care at all’ for 99.99% of people. How many care to contribute? It’s a quite small group. I’d suggest that a development.md become the file that has a better version of that data write up. The ‘Integrate beman.exemplar into your project’ section is the relevant part to 99.9% of users. That should be right below the example usage.
I think maybe some issues to simplify would be good.
1 Like
-1
Everything about usage and getting started needs to be in the ReadMe, effectively everything about the entire project except in-depth API docs. This is the expected usability metaphor and state-of-affairs for young and up-and-coming developers.
In the era of infinite-scroll, they want and expect to be presented with all the relevant information they need on the first Google result of the project. They expect it to be presented “newspaper”-style, with most important information up top and lower priority information down low. They expect to be able to Ctrl-F for keywords they need on a single page.
The guaranteed way to ensure a piece of documentation is completely unreachable is to put it in a wiki or docs page that requires click-through to find and explore. To limit search to those who have cloned the repo docs or using a website-specific search box.
Exemplar is in the sweet spot right now. My university students could use it exactly as is, which, if you’ve met the typical post-ChatGPT CS sophomore, is saying something.
The future is frightening. That said, I’m sure they can adapt to something that’s more minimal in the readme – with links to the boring bits – after all they have no attention span.
Sure, we can make it more minimal and the usability hit won’t be catastrophic, but my point is if we do so we’re doing it for us.
If this is the goal, helping new users, everything that isn’t detailed API docs should be in the ReadMe. That is the expected location and mechanism.
For experts none of this matters. I somehow managed to learn boost::asio, which has a formal documentation method of “cornering the authors in the hallway at C++ conferences”.
spipped:
Supported Platforms
This project officially supports:
- GNU GCC Compiler [version 11-15]
- LLVM Clang++ Compiler (with libstdc++ or libc++) [version 17-20]
- …
I have g++-15 and clang++-20 on my build host (OSX)
but it can’t be use with the cmake workflow presets provided?
Is this really huge Readme contents really helpful?
And if presets are only for some platforms, why are they visible on all?
bash-5.2$ cmake --list-presets
Available configure presets:
"gcc-debug" - GCC Debug Build
"gcc-release" - GCC Release Build
"llvm-debug" - Clang Debug Build
"llvm-release" - Clang Release Build
"appleclang-debug" - Appleclang Debug Build
"appleclang-release" - Appleclang Release Build
"msvc-debug" - MSVC Debug Build
"msvc-release" - MSVC Release Build
bash-5.2$
see clang++: error: linker command failed with exit code 1 · Issue #227 · bemanproject/exemplar · GitHub
This is a great conversation to have. Thanks for bringing it up @ednolan!
I think it is useful to consider what we want the user experience to be like under various scenarios. Here are a few examples:
- A moderately experienced C++ developer who needs some functionality and landed on the github page through via. Google search.
- A C++ developer who is curious about what’s being proposed for standardization and is browsing all the repositories.
- A student looking to gain some experience by participating in an active Open Source project.
- A C++ standardization committee member who is evaluating a library to inform their position.
I think for all of these, answering the questions “What is the purpose of this library?” and “What does code using this library look like?” are the first ones to answer.
The question that follows for at least a subset of scenarios will be “Can I use this library?”. In other words, does it require some compiler+flags combo that I have access to?
After this, I think the question is “How do I deepen my understanding of this library in a hands-on way?” Tutorials/examples/reference docs are great, but people also looking for a way to write their own code to experiment with.
Then, after all that, I think the questions fork. Some people want “How do I incorporate this library into my project?” and others want “How do I make contributions?”.
I’m curious to hear others’ thoughts on this.
1 Like
This seems foundational so that should always be first. In a future world where libraries have dedicated docs I think a link to that should also be right there because that’s often the next stop for anyone trying to use things. btw, there’s already a PR in website repo that demos how those docs can have live godbolt content – we likely can reuse that on readme as well. And inconsistently we have godbolt badge links: see scope library for an example.
This is where I was suggesting something like this would give an ‘at a glance’ overview
Usage Requirements (don’t like the title)
| Compiler | flags | Linux | MacOS | Windows |
|---|---|---|---|---|
| gcc (13-15) | c++20 | Passing | ||
| gcc(13-15) | c++23 | Passing | ||
| gcc(13-15) | c++26 | Passing | ||
| gcc-reflection | c++26 | Passing | ||
| mac-clang | c++23 | Passing | ||
| msvc | /c++:latest | Passing | ||
| joes-compiler | Unsupported |
– link to the licence.md file here
I think @purpleKarrot showed us something similar at C++Now for table of status.
Yep. Right now we’re following the first 2 elements decently, but things get inconsistent after that. As I probably already mentioned I think the ‘contributing guide’ could be another file linked from the readme that gets into all the details of setting up tests, etc.