Catch2
Catch2 copied to clipboard
catchorg
Improve documentation for new users
Description Improve documentation for first time users.
Additional context I am just starting to use Catch.
The first line of the tutorial presented on Catch's first page (https://github.com/catchorg/Catch2/blob/devel/docs/tutorial.md#top) says that ideally I should be using Catch2 through its "CMake integration" (https://github.com/catchorg/Catch2/blob/devel/docs/cmake-integration.md#top). I faithfully follow the "ideal" path.
On the second paragraph of the "CMake integration" page I start to get lost: If you do not need custom main function, you should...
Do I need a custom main function? Why would anyone need one? How can a person live without one? I have no idea at all and the text neither explains any of this nor provides any kind of sensible default orientation (If you don't know what we are talking about just pretend you... or something similar).
On the third paragraph it is presented a block of code and the reader gets to know that it should be enough to do the block of code. What is to do a block of code? Should I include this code in some pre existing file? Which file? In what part of said file? Or should I create a new file with the proposed content? Which file? Where should I put it?
It seems to me that this documentation that is presented to new users as their first contact with Catch is rather terse making lot's of assumptions not that reasonable for first time users.
@rsevero , if it makes you feel any better, I've been using Catch2 v2 with single header file for years, and I struggled for hours to get Catch2 v3 working with CMake given current Catch2 v3 documentation. Full disclosure, I've been using CMake for days (not weeks, not years).
Maybe the following project I created would be helpful to you. This is the most minimal successful usage of Catch2 v3 I'm aware of at this time, and I welcome suggestions for further simplification:
https://github.com/dksmiffs/simplest-catch2v3
I will consider rewriting the docs to guide the reader more strongly towards the default set up, but I generally do not want Catch2's documentation to explain things like build systems or C++ language rules, unless relevant to Catch2.
This means that there will always be an assumption that the user knows their way around CMake, or whichever build system they use.
Hi. One aspect of the doc that could be improved now that Catch2 v3 is split into several headers, is that the doc should mentions which headers we should include for different features of Catch2, e.g. INFO, Approx, BENCHMARK, etc. It's not too hard to figure it out looking at the files themselves, but not having to guess would be great.
