xk6-disruptor: add a first-steps monopage

[roobre]

This PR continues the work started on #1356, creating a single-page aimed to onboard people into trying the disruptor with as little friction as possible.

The included examples borrow some explanation from other pages, introducing a bit of redundancy as the price to pay to avoid too many cross-references.

The examples use and reference QuickPizza as a demo application.

[pablochacin]

In general, my impression is that the first steps page tries to cover multiple objectives introducing some overlapping.

My suggestions have two goals:

1. Separate the generic first steps (requirements, installation) from the example. In particular, move the installation of the demo application to the example part
2. Streamline the example to show the key disruptor functionality, removing some text that serves more like an introduction to the project. For this, we have the main project page.

In general, I'm still not sure this page has any benefit over the existing pages except puting everything in one place.

[pablochacin]

Suggested change

	- A microservice-based application that communicates over HTTP or GRPC.
	- A cloud-native application that communicates over HTTP or GRPC.

[pablochacin]

Which privileges are needed?

[pablochacin]

Suggested change

	- The ability to reach at least one service exposed by the application from the machine where you will run the tests.
	- The ability to reach the service you want to test from the machine where you will run the tests.

I would also add a reference to "exposing your application".

[pablochacin]

Suggested change

	You can download the latest release for your architecture and platfrom from https://github.com/grafana/xk6-disruptor/releases. Look for the files named `xk6-disruptor-v*`, not `xk6-disruptor-agent-v*`: The latter are for advanced users and developers only.
	You can download the latest release for your architecture and platfrom from https://github.com/grafana/xk6-disruptor/releases. Look for the files named `xk6-disruptor-v*`, not `xk6-disruptor-agent-v*`: The latter is the agent, explained in [how it works](/docs/k6/<K6_VERSION>/testing-guides/injecting-faults-with-xk6-disruptor/how--it-works)

[pablochacin]

Suggested change

k6 was born and is often referred to as a load testing tool. However, with the flexibility that testing as code provides, and the large amount of extensions (such as xk6-disruptor) it has, a better way to think about k6 is as a reliability testing tool. We will now write a k6 test that checks if an API is behaving correctly, without putting enough load on it to significantly alter its behavior.

[pablochacin]

Suggested change




[pablochacin]

I think we should focus on the example. If the reader already has an application, how does this guide help?

Suggested change

	xk6-disruptor focuses on injecting faults on applications running in Kubernetes. If you already have your application deployed to a development Kubernetes cluster, you are all set! If you don't, we will guide you through deploying a demo application on a local `minikube` cluster.
	xk6-disruptor focuses on injecting faults into applications running in Kubernetes. If you already have access to a development Kubernetes cluster, you are all set! If you don't, we will guide you through deploying a demo application on a local `minikube` cluster.

[roobre]

I was thinking the opposite, actually: I added the example so people can still follow if they don't have their application deployed and accessible right when they are reading the article, but my original intention was for the guide to be the point of reference for developers/sres who do have an application and want to start using the disruptor. I think this was the feedback we got and originated this page: "I have an application but the multi-paged structure is hard to follow end to end to get me from zero to something"

[pablochacin]

I added the example so people can still follow if they don't have their application deployed and accessible right when they are reading the article
think this was the feedback we got and originated this page: "I have an application but the multi-paged structure is hard to follow end to end to get me from zero to something"

That is still the goal and I understand the intention, but my own experience reading the content was the opposite.
It was unclear what the general steps are and what is specific to the demo. And the example makes a very long chunk of text and code in the middle of the guide!

The main problem I see is that any example with the disruptor API would be application specific.

I still think it would be better to put all the steps together and then demo them in an example. In this way, if someone already has an application the demo won't be in the middle.

[pablochacin]

Suggested change

	## Use our demo application
	## Deploy the demo application

[pablochacin]

I think this section should go in its own high-level section, before the "creating a simple test" section.

[pablochacin]

Suggested change

	const BASE_URL = 'http://localhost:3333'; // <- Your reachable endpoint goes here.
	const BASE_URL = 'http://localhost:3333'; // this is endpoint where the recommendations service is exposed

[roobre]

Thanks for your thoughts @pablochacin!

I think it might be worth commenting on the general comments before jumping into the specific suggestions.

Separate the generic first steps (requirements, installation) from the example. In particular, move the installation of the demo application to the example part

I agree with this. My goal was to make the page easy to follow to people who both have an application already and people who do not, but I'm not extremely happy with the result either. I'm not sure I understand your position in this. Do you prefer to focus the guide on the demo application, or do you prefer a more clear separation, for example using collapsible elements or something along those lines?

Streamline the example to show the key disruptor functionality, removing some text that serves more like an introduction to the project. For this, we have the main project page.

My assumption was that duplicating this information was a good thing: People who have read the main page will skip those paragraphs, and people who jump directly to hands-on tutorials without reading the theory will get some useful context. That being said, I understand this is kind of an style choice so I can scrap those parts out if we don't like the tradeoff.

[pablochacin]

Do you prefer to focus the guide on the demo application, or do you prefer a more clear separation, for example using collapsible elements or something along those lines?

As I explained in a previous comment, my main concern is that mixing the guide with the example makes the text too long and at times it is not clear what it's specific to the demo.

The idea of collapsible may work, but then I think we should define the general structure that is useful for anyone who already has an application and then add examples along the way. The way it is structured and written now doesn't make this clear to me.

[pablochacin]

My assumption was that duplicating this information was a good thing: People who have read the main page will skip those paragraphs, and people who jump directly to hands-on tutorials without reading the theory will get some useful context.

I think this goes against some practices in documentation that we discussed time ago with the k6 documentation folks. In particular, that each piece of content should have a clear objective and audience in mind.

We should try to stick to one simple goal in this page: make it easier fo someone to start using the disruptor in their project.