# Making exemplar/README.md more concise

**URL:** <https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462>\
**Category:** Beman Website and Docs\
**Created:** [July 8, 2025, 12:33am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462 "2025-07-08T00:33:49Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![ednolan](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/ednolan/32/131_2.png) [@ednolan](https://discourse.bemanproject.org/u/ednolan)\
**Post date:** [July 8, 2025, 12:33am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/1 "2025-07-08T00:33:49Z")

</div>

> <https://github.com/bemanproject/exemplar/blob/main/README.md>

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?

---

<div class="post-metadata">

**Author:** ![Jeff-Garland](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/jeff-garland/32/23_2.png) [@Jeff-Garland](https://discourse.bemanproject.org/u/Jeff-Garland)\
**Post date:** [July 9, 2025, 1:45am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/2 "2025-07-09T01:45:27Z")

</div>

> [@ednolan](#):
>
> 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.

---

<div class="post-metadata">

**Author:** ![vito.gamberini](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/vito.gamberini/32/261_2.png) [@vito.gamberini](https://discourse.bemanproject.org/u/vito.gamberini)\
**Post date:** [July 9, 2025, 3:52pm UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/3 "2025-07-09T15:52:03Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Jeff-Garland](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/jeff-garland/32/23_2.png) [@Jeff-Garland](https://discourse.bemanproject.org/u/Jeff-Garland)\
**Post date:** [July 10, 2025, 3:20am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/4 "2025-07-10T03:20:49Z")

</div>

> [@vito.gamberini](#):
>
> 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.

---

<div class="post-metadata">

**Author:** ![vito.gamberini](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/vito.gamberini/32/261_2.png) [@vito.gamberini](https://discourse.bemanproject.org/u/vito.gamberini)\
**Post date:** [July 10, 2025, 3:33am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/5 "2025-07-10T03:33:26Z")

</div>

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_.

> [@ednolan](#):
>
> I think this runs the risk of overwhelming new users

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

---

<div class="post-metadata">

**Author:** ![ClausKlein](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/clausklein/32/136_2.png) [@ClausKlein](https://discourse.bemanproject.org/u/ClausKlein)\
**Post date:** [July 10, 2025, 5:20am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/6 "2025-07-10T05:20:37Z")

</div>

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
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](https://github.com/bemanproject/exemplar/issues/227)

---

<div class="post-metadata">

**Author:** ![dsankel](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/dsankel/32/5_2.png) [@dsankel](https://discourse.bemanproject.org/u/dsankel)\
**Post date:** [July 14, 2025, 3:52pm UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/7 "2025-07-14T15:52:13Z")

</div>

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:

1. A moderately experienced C++ developer who needs some functionality and landed on the github page through via. Google search.
2. A C++ developer who is curious about what’s being proposed for standardization and is browsing all the repositories.
3. A student looking to gain some experience by participating in an active Open Source project.
4. 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.

---

<div class="post-metadata">

**Author:** ![Jeff-Garland](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/jeff-garland/32/23_2.png) [@Jeff-Garland](https://discourse.bemanproject.org/u/Jeff-Garland)\
**Post date:** [July 18, 2025, 6:17pm UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/8 "2025-07-18T18:17:17Z")

</div>

> [@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](https://github.com/bemanproject/scope) 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.

---

<div class="post-metadata">

**Author:** ![ednolan](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/ednolan/32/131_2.png) [@ednolan](https://discourse.bemanproject.org/u/ednolan)\
**Post date:** [March 9, 2026, 5:37am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/9 "2026-03-09T05:37:23Z")

</div>

> I think the ‘contributing guide’ could be another file linked from the readme that gets into all the details of setting up tests, etc.

I put up a pull request to do this: [Move README's Development section into CONTRIBUTING.md by ednolan · Pull Request #308 · bemanproject/exemplar · GitHub](https://github.com/bemanproject/exemplar/pull/308)

---

<div class="post-metadata">

**Author:** ![ednolan](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/ednolan/32/131_2.png) [@ednolan](https://discourse.bemanproject.org/u/ednolan)\
**Post date:** [March 16, 2026, 3:59am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/10 "2026-03-16T03:59:14Z")

</div>

I have a pull request here that simplifies, rewords, and cleans up the README.md and CONTRIBUTING.md files:

> <https://github.com/bemanproject/exemplar/pull/323>
>
> \- Update CMake version in README
> \- Cookiecutter: Fix a missed minimum C++ versi…on variable
> \- Remove language about C++20 range requirements in tests
> - This should be obvious to users if and when they encounter the error, and this language kept being copied into the READMEs of other libraries when it wasn't relevant.
> \- Remove CMAKE\_PREFIX\_PATH parameter from CONTRIBUTING.md documentation
> - This hasn't been necessary since 2a8725d98d53923a76bb0c49e3c7a5b192ce9ff1 but the update to the README was missed.
> \- Refactor "Integrate beman.exemplar into your project" README section
> - This section is now split up into four sections: Build, Installation, CMake Configuration, and Using beman.exemplar. Some of the verbiage has been rewritten.
> \- Remove GitHub Codespace language from CONTRIBUTING.md
> - I am sunsetting the Beman project's use of GitHub codespaces due to maintenance burden, and a poor developer experience caused by excessive load times for launching the codespace instances.
> \- Remove language around installing build requirements
> - Information about how to install CMake, LLVM, and MSVC is a quick Google search away. This document is more valuable if we stick to the information that's specifically relevant to building Beman libraries.
> \- Refactor language in CONTRIBUTING.md
> - There are no major changes to the substance of what the document communicates in this commit, but it rephrases some of the language to make it clearer.

---

<div class="post-metadata">

**Author:** ![neatudarius](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/neatudarius/32/70_2.png) [@neatudarius](https://discourse.bemanproject.org/u/neatudarius)\
**Post date:** [March 16, 2026, 5:44am UTC](https://discourse.bemanproject.org/t/making-exemplar-readme-md-more-concise/462/11 "2026-03-16T05:44:12Z")

</div>

LGTM!

I think we should add an entry about CONTRIBUTING.md file to the Beman Standard.