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. • Read and edit workload modules in k6 learn.
2. • Read through and copy edit docs
3. • Restructure as necessary
4. • Add content as necessary

Relevant links

• Release for v0.27.0, which contained PR New executors k6#1007, explains the then-new executors feature.

[na--]

"workhorse", not "workhouse" 😂 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:

#231 (comment)

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: #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:

• Document how VUs are scheduled post-v0.27.0 #62
• Document how VUs are cycled in arrival-rate executors #136
• Mention coordinated omission in arrival-rate docs #231
  • https://community.k6.io/t/is-k6-safe-from-the-coordinated-omission-problem/1484
• Add examples for scenario reuse #255
  • https://community.k6.io/t/run-two-several-scenario-files-in-parallel-or-serially-using-single-file/1584
• Can I run two scripts at the same time by a command? k6#1918
• Update docs for REST API commands #367
• Explain what progress is for different executors #400
• Add an example for running scenarios sequentially #444
  • https://community.k6.io/t/run-tests-sequentially/1310
  • https://community.k6.io/t/sequentially-run-scenarios/1004
• Improve wording around graceful stop  #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 7718690...83c23cb

all worked on simplifying executor comments and language