Make docs more discoverable by changing the FAQ section
@inqueue is already working on this.
Since Jul 26, 2022.
- Dominant language
- Python
- Stars
- 2k
- Forks
- 348
- Avg merge
- 6d 17h
- Merged PRs (30d)
- 5
Description
Description
We are seeing a recurring pattern of users not being able to easily find answers to common questions in our docs. The docs are thorough but pertinent information maybe scattered across different sections.
Several examples can be found in the discuss forums, users wondering how to abort benchmarks when there are errors, killing lingering Rally processes, which pipeline to use etc.
In this ticket I am proposing that we elevate the significance of our existing FAQ section by making it similar to a bookmarks page.
More concretely, currently we have some questions in the FAQ section and some of them have long answers.
Instead we should keep the detailed content in sections outside of FAQ (mostly it's like this now) and use a question->link format for FAQ; see the example below.
I also propose that we move the location of FAQ from currently bottom under Additional Information to the very top of the page either in a section of its own or somewhere in the Getting started section.
FAQ/How to example
-
How to make Rally terminate the benchmark when it encounters errors?
See on-error=abort command line flag.
-
Unable to restart Rally, it complains about running processes
See kill-running-processes command line flag.
-
I want to benchmark a remote cluster without Rally provisioning Elasticsearch for me:
Refer to the benchmark-only pipeline.
etc.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.