Request

This issue is for capturing actions arising from @horenmar 's request on Discord of 2019-06-15 "Help wanted: documentation"

The current documentation is pretty okay, but it definitely shows that it has evolved over multiple years, using different expository styles and was targeted at different audience.

And as the feature set grows, the documentation needs to become more hierarchical, and there also needs to be a split between expository, tutorialish, documentation for people who are starting out with Catch, and the reference documentation for people who are already comfortable with Catch, but need to find out e.g. customization points for generators

Also, completely separately, because the number of issues that go "Feature X does not work.", "Have you tried updating to a version where the feature actually is?" "Uhhh", the documentation probably also needs to document when a feature was introduced.

We (Clare and Martin, in discussion) have agreed we'll stick with Markdown for now and see how far we can get with improving the docs - so moving to things that need a separate rendering/processing step e.g. sphinx, Doxygen, ASCIIdoc is out of scope for this ticket

Types of user

The intention is to consider 3 categories of user:

1. Those who have brand new to Catch - seeing the docs for the first time - who want to be guided through
2. Advanced users who want to customise things
3. Experts, who want a full reference

Good examples

Examples of the kind of thing wanted:

• The Python 3.3. documentation page - which clearly separates Tutorial material from reference material. (The tutorial as 14 different sections and is quite long - a nice thing about it is the density of examples, e.g. see 4.3 The range() function)

General Actions

• #1695 For recently-added features, add "Introduced in Catch 2.x.y" to the documentation - see https://docs.gitlab.com/ee/ci/variables/#variable-types for an example
• Find a way to give different ways to jump in to the documentation, depending on level of knowledge (See Python 3.3 example above for the kind of thing being thought of)

Pages - and actions for them

• assertions.md
  • Review the table of contents
  • Thread safety bit is better near the top of the page, rather than a section in its right
  • Bit on commas could be integrated with the remainder
• benchmarks.md
• ci-and-misc.md
• cmake-integration.md
• command-line.md
  • The return codes an user can get from the binary should be documented.
• commercial-users.md
• configuration.md
  • Make it clear that configuration macros should be defined in all translation units to avoid ODRV.
• contributing.md
• deprecations.md
• event-listeners.md
• generators.md
• limitations.md
• list-of-examples.md
• logging.md
• matchers.md
• opensource-users.md
• other-macros.md
• own-main.md
• Readme.md
• release-notes.md
• release-process.md
• reporters.md
  • Give some kind of overview of what reporters do
  • Provide some more info on writing custom reporters
• slow-compiles.md
• test-cases-and-sections.md
• test-fixtures.md
• tostring.md
• tutorial.md
  • Some of the questions seen in this area are of the kind "how do I compile C++" - agreed that teaching this is not in the scope of Catch docs
• why-catch.md