Split documentation due to markdown files

[tcojean]

Currently in Ginkgo, we detail available features and options at a high level in markdown files (BENCHMARKING.md, TESTING.md, INSTALL.md, ...) on top of documenting the features also directly in the source code. There is of course strong interest in these markdown files since it's an easier documentation format for the user and also allows to find what Ginkgo can do in an easy fashion, but this documentation duplication means that multiple places (may) need to be updated when changing/adding some feature. This issue is for discussing this question.

There are multiple options for tackling this problem, some are maybe not very realistic though:

1. Add comments in the source code to notice any developer to also update the related file whenever appropriate. This might require to add these comments to many places.
2. Find a way to automatically export the source code documentation to the markdown files? I believe we could mark the areas to be exported with header comments, but I'm not sure how feasible parsing all of this is, and sometimes the options aren't only listed but also referred to in the text, so this would not solve all problems.