Would a PR to tweak the docs be welcome?

[josephjunker]

💡 Idea

I think that some slight rearranging of the docs could make the project easier to approach for beginners.

Motivation

I've introduced a few people to fast-check, and while they've all picked it up eventually, they've also tended to struggle with understanding it from the fast-check.dev website alone. Also, as someone who is very familiar with property-based testing I still sometimes have a hard time finding what I'm looking for.

Example

The specific changes I would make would be:

• Inline some of the combiner docs, such as merging stringMatching into string.
  • This is motivated by me reading the string docs, wishing I had something like stringMatching, and not finding it until it was pointed out to me by someone else.
• Flatten the sidebar somewhat. Move Arbitraries, Properties, and Runners up a level, eliminating the Core Blocks directory. Within the Arbitraries directory, remove the intermediate directories and present the various combinators as a flat list. Break a number of the individual arbitraries into their own pages.
  • This is motivated by wanting an easier way to see everything that's available. Approaching the project initially, it's not clear what a "Core Block" is, or why that's where I'd look for functions. Within the arbitraries directory, the distinctions and groupings feel a little, well, arbitrary. If I want a Set I wouldn't expect to have to look under the documentation for Object, for example.
• Split the "Why Property-Based" section into two pieces: "What is Property-Based Testing?" and "Why Use Property-Based Testing?". Move "What is Property-Based Testing" to before the "Getting Started" section, and link to it on additional pages.
  • This is motivated by it taking surprisingly long for a beginner to this project to find out what this project actually does. Someone who isn't aware of property based testing has to see examples of it in action before they have motivation for why these examples look the way they do, which can come off as intimidating.

I would not touch the front page of the website, only the /docs section.

If it's acceptable I might suggest additional tweaks to wording here and there. I do have some experience with technical writing (personal blog) and I am extremely ok with my own writing style being amended or my edits being rejected, so I won't be defensive if there are any further tweaks required on the PR.

[dubzzz]

Definitely welcomed! Probably open them as distinct PRs so that I can merge some and we can rediscuss others.

• For the "Inline some of the combiner docs", clearly a good point. The stringMatching should have been put next to string.
• For the structure, definitely there is something to rework.
• For the split what/why I trust you.