Improvement of welcoming documentation

[aurelien-reeves]

Improvement of README and CONTRIBUTING documents as part of cucumber/common#1521

[mattwynne]

This looks great! I wonder if we should explain more about the relationship with the core gem, and how to set up a development environment that includes both.

[mattwynne]

There's also nothing mentioned (unless I missed it) about the standards we expect from PR submissions - TDD/test coverage, rubocop linting etc. That might be helpful. We could also explicitly point out that we full-time maintainers are available for 1:1 pairing sessions to coach people with their submissions. I'd happily make my calendly link available in this document.

[mattwynne]

Maybe that latter stuff belongs more in a PR template

[mattwynne]

Relevant: https://docs.github.com/en/communities

[aurelien-reeves]

This looks great! I wonder if we should explain more about the relationship with the core gem, and how to set up a development environment that includes both.

I though that it would be more relevant in the core repo, or maybe in an ARCHITECTURE.md shared across the cucumber-ruby repositories. Or maybe in the wiki?

There's also nothing mentioned (unless I missed it) about the standards we expect from PR submissions - TDD/test coverage, rubocop linting etc. That might be helpful.

Actually I wanted to put that in the PR template. And remain pretty gentle with this. There are not too many PR, we can guide contributors through "our" expected standards as part of the reviews. That would let the welcoming document neater.

We could also explicitly point out that we full-time maintainers are available for 1:1 pairing sessions to coach people with their submissions. I'd happily make my calendly link available in this document.

Yes, that could be interesting indeed 👍

To sum-up, my strategy here is to to avoid the README and the CONTRIBUTING to be overwhelming but to distill the info all along the process a new contributor would follow when sending a first PR.

[mattwynne]

Yes, I like the layered approach, making this entry-point doc not too long and leaving depth to other docs. From having paired with @eduardrudko on his PR, I could see that the two-gem situation caused him some confusion at first, so for example the setup with the environment variables to override Gemfile paths needs to be documented.

Maybe instead of documenting it we should just bite the bullet and merge the two repos into a one little cucumber-ruby monorepo with both gems in it?

[mattwynne]

Actually I wanted to put that in the PR template. And remain pretty gentle with this.

Oh yes, I agree we should be gentle and constructive. I think that setting expectations can be kind and supportive - because it will be frustrating for someone to make a PR and then be told later "could you write some tests for this please?"

[aurelien-reeves]

the core gem, and how to set up a development environment that includes both.

Just added a new chapter dedicated to cucumber-ruby-core. For now it do not say that much. I suggest to complete it once we have more document related to it in cucumber-ruby-core, or in the wiki, or somewhere else. I would avoid to put too many info here.

[aurelien-reeves]

Refs cucumber/docs/pull/635

There's also nothing mentioned (unless I missed it) about the standards we expect from PR submissions - TDD/test coverage, rubocop linting etc. That might be helpful. We could also explicitly point out that we full-time maintainers are available for 1:1 pairing sessions to coach people with their submissions. I'd happily make my calendly link available in this document.

I've updated the PR template, and added some refs. to full-time maintainers.

[mattwynne]

Does rubocop not run as part of CI?

[aurelien-reeves]

Yes it is.
But it is also really frustrating to have the CI failing because of rubocop.

This is a way to warn the developer before it happened.

[mattwynne]

My overall thoughts about this change are:

1. It makes things a lot better, and we should merge it ASAP
2. The contributing file is still very long, and I wonder if we can push some of the details off into other files in the /docs folder to keep it more concise and therefore approachable.
3. The example in the README (features/rule.feature) is a bit contrived / self-referential and might not do a great job of illustrating how to use Cucumber. I wonder if we should just link to the https://cucumber.io/docs/guides/10-minute-tutorial/ instead

In any case, I'd merge this and we can iterate from there.

I'd really love to do some user testing and get feedback from real users of this stuff.

[aurelien-reeves]

2. The contributing file is still very long, and I wonder if we can push some of the details off into other files in the /docs folder to keep it more concise and therefore approachable.

Yeah, I agree.
I still like the approach of nextcloud. Their main "how to contribute" page is hosted on their website: https://nextcloud.com/contribute/
That would free the CONTRIBUTING.md in the repo from anything else than contribution dedicated to the code.

3. The example in the README (features/rule.feature) is a bit contrived / self-referential and might not do a great job of illustrating how to use Cucumber. I wonder if we should just link to the https://cucumber.io/docs/guides/10-minute-tutorial/ instead

The purpose of that example in the readme is to show a minimal example to show that cucumber is properly installed and running. The minimal reproducible example of it being working 😅

It is not an illustration of how to use Cucumber.

For illustrating how to use Cucumber, the section after that is redirecting to the documentation itself.

I'd really love to do some user testing and get feedback from real users of this stuff.

+1