Restructure and rewrite Scenarios section

[MattDodsonEnglish]

Scenarios are among the most important parts of the k6 API. But, frequent user questions and doubts about configuring them show that the docs could be confused. Subjectively, I can say that I find them confusing. I still need to read the docs for each executor carefully to figure out what workload to use.

Some preliminary issues:

• What's a "workhouse?" Let's reduce metaphorical language and be precise about what we mean.
• Similarly, what's a "workload?" We probably need to define that.
• "When to use" is buried in the topic for each executor. Let's move that to the top page.
• On the top page, a visual comparison of each workload would be nice, perhaps in a small mutiple.
• Perhaps a flow chart would help users choose an executor.

Sequence to solve this issue:

1. • [x] Read and edit workload modules in k6 learn.
2. • [x] Read through and copy edit docs
3. • [x] Restructure as necessary
4. • [ ] Add content as necessary

Relevant links

• Release for v0.27.0, which contained PR https://github.com/grafana/k6/pull/1007, explains the then-new executors feature.

[na--]

"workhorse", not "workhouse" :joy: But yeah, I agree the docs can be improved a ton here. One suggestion I have is to add a use-case based table with "if you want to do X, you should use executor Y in your scenario".

[MattDodsonEnglish]

I was going to post about metioning the coordinated omission problem, but there's already an issue:

https://github.com/grafana/k6-docs/issues/231#issue-824581069

Besides the forum post, it got brought up in discussion about a blog that used k6 to bench mark load balancers: https://news.ycombinator.com/item?id=32867684

Really, to fix this, we could just stick the term somewhere in https://k6.io/docs/using-k6/scenarios/arrival-rate/. That would help googlers.

[MattDodsonEnglish]

This Office Hours has some good discussion on the different use cases for each scenario: https://www.youtube.com/watch?v=ypli_y3UryU

[MattDodsonEnglish]

Related: https://github.com/grafana/k6-docs/issues/615

[MattDodsonEnglish]

As I went through the old issues, I collected all the ones about scenarios. It's quite a list! I guess to close this issue, we should try and close all of these, too:

• [ ] https://github.com/grafana/k6-docs/issues/62
• [x] https://github.com/grafana/k6-docs/issues/136
• [x] https://github.com/grafana/k6-docs/issues/231
  • https://community.k6.io/t/is-k6-safe-from-the-coordinated-omission-problem/1484
• [ ] https://github.com/grafana/k6-docs/issues/255
  • https://community.k6.io/t/run-two-several-scenario-files-in-parallel-or-serially-using-single-file/1584
• [x] https://github.com/grafana/k6/issues/1918
• [ ] https://github.com/grafana/k6-docs/issues/367
• [ ] https://github.com/grafana/k6-docs/issues/400
• [x] https://github.com/grafana/k6-docs/issues/444
  • https://community.k6.io/t/run-tests-sequentially/1310
  • https://community.k6.io/t/sequentially-run-scenarios/1004
• [x] https://github.com/grafana/k6-docs/issues/1062

And some forum posts

https://community.k6.io/t/how-to-distribute-vus-across-different-scenarios-with-k6/49/11 https://community.k6.io/t/pause-a-ramping-vus-test-execution-then-resume-it-by-terminal-command/2043/2

[immavalls]

This forum topic is relevant: https://community.k6.io/t/about-the-number-of-users-in-the-stress-test-documentation/6131/3 I believe it shows our scenario docs and https://k6.io/docs/test-types/stress-testing/#api-stress-test-in-k6 can still be a bit confusing.

[MattDodsonEnglish]

Commits https://github.com/grafana/k6-docs/compare/7718690ab458f67be558fa22475e1e4fcefa2f21...83c23cb4ed51be634d2304673a6ee4e332a033e6

all worked on simplifying executor comments and language