search

grafana / k6-docs

The k6 documentation website.
https://grafana.com/docs/k6/latest/
89 stars 223 forks source link

Missing documentation for using a k6chaijs plugin #857

Open imiric opened 2 years ago

imiric commented 2 years ago

Currently, the k6chaijs page mentions:

It's possible to extend the default functionality with Chai plugins. Follow the build instructions on the project repository.

Yet the build instructions in the k6chaijs repository simply have:

npm install
npm run-script webpack

And don't give any additional details about how to use plugins.

Some users are understandably confused by this.

I proposed a couple of alternatives, but I'm not sure if either is the "right" way, or if there's something better/easier, so @sniku @e-fisher or @2Steaks would know better.

I'm also not sure if this should be documented on the k6-docs page or in the k6chaijs repo, so feel free to move this issue to the k6chaijs repo if it makes more sense there.

ppcano commented 2 years ago

https://github.com/grafana/k6-docs/commit/fb365c7f286566994ba2eb14cd601c04376df84d adds the link to the proposed solutions in the Chai Plugin section:

It's possible to extend the default functionality with Chai plugins. To use a plugin or build a Chai version with plugins, follow the instructions in this example.

imiric commented 2 years ago

@ppcano I think that's a cop-out! :smile:

We should verify whether those instructions make sense, and then integrate them in either the k6chaijs repository, or in k6-docs. I think the k6chaijs README might be a better place for it, actually.

I can do that myself, but I wanted confirmation from the k6chaijs maintainers on the way to proceed. (Or preferably for one of them to validate and pick that work up.)

IMO we shouldn't link to a forum post from k6-docs. We can't rely on external resources for documentation, and it's just bad UX, regardless of who the post author is.

ppcano commented 2 years ago

@imiric I assumed you tested it and worked.

Note that I didn't close the issue.

For various internal reasons, this issue could take long time till is resolved. Meanwhile I think it is better to reference to these instructions than nothing.

IMO we shouldn't link to a forum post from k6-docs. We can't rely on external resources for documentation, and it's just bad UX, regardless of who the post author is.

I don't disagree. But I believe pointing to a solution helps more in this case.

ppcano commented 2 years ago

the k6chaijs README might be a better place for it

I'd go for this one as well. And open an issue on the project.