Discussion around general improvements of the documentation

[aurelien-reeves]

We've discussed this previously in the open source weekly meetings.

I think we should abandon the whole language tab idea and move more of the platform-specific documentation to plain old GitHub Markdown files in the respective Cucumber-* repositories. We're doing this already here: https://github.com/cucumber/cucumber-js#documentation

The reason I want to abandon it is that it's too difficult to write documentation this way. There are lots of if statements in the Markdown code to display/hide contents for various languages.

• Some sections don't have language specific content and just show up blank
• Some content is so platform-specific that we couldn't possibly have language-specific content
• These if statements are cumbersome to edit
• We cannot easily version the docs (but we can if we do like Cucumber.js does)
• It's easier for contributors to update docs when they are in the same repo as the code

We can keep high-level platform-agnostic content where it is now though.

• We cannot version the docs

Originally posted by @aslakhellesoy in #628 (comment)

[aurelien-reeves]

We may distinguish

• basic usage of cucumber, which still rely on specific languages, but could still be part of the documentation
• more advanced and specific usage of cucumber, which could be describe on github wikis and referenced from the documentation if needed

For example the 10 minute tutorial are pretty fine as they are now, but parallel execution is too specific and could be moved elsewhere.

On my own, I think a dedicated documentation website for basic usage still makes sense. It is still easier for some user.
I agree it is difficult to maintain, but to me it feels like a necessary evil.

[davidjgoss]

I agree with slimming down what's on the website. I had a quick scan and there's quite a bit of JS content that's now outdated that I didn't previously know about - so it's doing more harm than if it wasn't there at all.

[aslakhellesoy]

Relevant: https://daniel.haxx.se/blog/2021/09/04/making-world-class-docs-takes-effort/

[mlvandijk]

Quite a while ago the idea was just the opposite, see #188.