Making exemplar/README.md more concise

[Jeff-Garland]

@dsankel

I think it is useful to consider what we want the user experience to be like under various scenarios. Here are a few examples:

…details suppressed…

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.

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.

@dsankel

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?

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.

@dsankel

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?”.

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.