Improve documentation for new users
- Dominant language
- C++
- Stars
- 21.5k
- Forks
- 3.5k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 2
Description
**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.
Contributor guide
Research direction
Start with docs/tutorial.md and docs/cmake-integration.md, especially the linked introductory sections. Read the setup flow as a first-time Catch user and clarify when a custom main function is needed, what the default path is, and where the shown code belongs. Done means a new user can follow the CMake integration without guessing which file to edit or create.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100