Set up outline structure for User Guide

[claremacrae]

I've started a page to write an outline for a User Guide for this library.

https://github.com/approvals/ApprovalTests.cpp/blob/master/doc/README.md

I'm struggling to come up with useful section headings and page titles, so this ticket is to propose a structure, and seek feedback on it, before much work is done on the actual writing.

[claremacrae]

Here are some tutorials in other C++ projects that I think are well-structured:

• https://github.com/catchorg/Catch2/blob/master/docs/Readme.md
• https://sinusoid.es/immer/#contents
• https://github.com/emil-e/rapidcheck/blob/master/doc/user_guide.md
  • (https://github.com/emil-e/rapidcheck/blob/master/README.md is good as well)

Extra pointers appreciated!

[barneydellar]

In the Introduction, I would add in a “What is Approval Testing” section first, just so people know what kind of thing they’re looking at.

[claremacrae]

In the Introduction, I would add in a “What is Approval Testing” section first, just so people know what kind of thing they’re looking at.

Done! Thanks @barneydellar

[claremacrae]

Maybe add something like “Requirements and Dependencies”

[claremacrae]

A nice trick that the Catch2 docs use is to put a top target in each page, and then link like this:

https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md#top

This hides all the github boilerplate UI at the top of the page, so all the reader sees is the documentation, which makes it look a bit more professional.

[claremacrae]

Once the structure settles down, add a Contents section at the start of each page - see the Catch2 tutorial link above.

[claremacrae]

I'm going to declare the structure of the User Guide as good enough, and crack on with filling in the blanks. So marking this as closed.