Improve READMEs and CONTRIBUTING documents

[aurelien-reeves]

Our README and CONTRIBUTING documents may certainly be more welcome, and standardize.

Would anyone have ideas? Or source for inspiration?

My self I've spotted how Nextcloud is welcoming contributors with a dedicated landing page, and a developer manual

• https://nextcloud.com/contribute/
• https://docs.nextcloud.com/server/latest/developer_manual/getting_started/index.html

However that may request some maintenance on a regular basis

And Ruby on Rails also has a dedicated page on their website with a lot of technical details for incoming developers

• https://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html

[davidjgoss]

On the README side of things for users, I think the cucumber-js one could really use an overhaul.

I really like the README for ava https://github.com/avajs/ava

In particular:

• Logo reassures you found the right thing
• No build/stats badges - [whispers] I tend to view them as just clutter these days
• Little animation showing the tool in action
• Enough info to get you started with a test that runs, and then links to detailed docs
• Early callout to potential contributors to funnel them into the CONTRIBUTING doc

WDYT?

[aurelien-reeves]

I agree.
We are focus on contributors, but I still think READMEs should introduce properly the tool, quickly, to users before redirecting them to the documentation website.

[davidjgoss]

Great - I'll run up a PR for cucumber-js soon and will try and come back with some thoughts on contrubuting docs too.

[aurelien-reeves]

The contributing guide for atom is pretty great!

[aurelien-reeves]

Here's a first iteration on cucumber-ruby: cucumber/cucumber-ruby#1542

[mattwynne]

Slightly tangential, but I learned about this feature of GitHub today: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file

e.g. https://github.com/Homebrew/.github

[funficient]

For what it's worth, this was what I was looking for when I wanted to get started (on a very high level):

https://app.conceptboard.com/board/mc7s-g0d3-goao-48ey-cmfr

[mpkorstanje]

End user architecture diagram. Good one. JVM definitely needs that. Thanks.

[mattwynne]

@funficient this is super useful, thanks so much for sharing!

Do you think we should rework the /docs welcome page to offer these three signposts (instead of jumping into installation, which is somewhere down the "Use product" flow)?

[funficient]

@mattwynne I know too little to recommend any reworks yet. I do know it's too hard to find and make sense of all the information that is there, so yes. Eventually.

Not sure if this is the right place to add the following comments...

I would start at the entry point which is the website as that's where users will start. I would also handle it as part of the 'breaking down the monolith' project. It feels as if it is the same project to me? The architecture needs to be re-looked at and reworked, and one of the outcomes should include updated documentation. Epic = break down the monolith, Stories = redefine architecture; identify re-usable components / classes ; refactor / move component 1; ..... for example.

User needs in terms of documentation (as far as I can see):

You have two main users (in terms of product) as far as I can see - the user and the contributor. I don't think it makes sense to become a contributor if you haven't first used the product to understand the business rules. A user thus becomes a contributor.

A high-level user journey could be:

• New user discovers and starts using Cucumber (they want to understand the value proposition, where and when to use it and how it works). This is mainly on the website.
• Existing user struggles using the product and need help. They go to slack and become part of the community from there.
• Existing user loves the product so much that they want to contribute. This is mainly via Cucumber school? and Github.

The alternative use case catering for open source contributors could be:

• A new contributor looks for an open source project to contribute and want to get started. They will follow the same high-level user journey above, but maybe a more concise version of the new user (just an overview).

[funficient]

I added a brief breakdown of how I see the journey from newbie to brand ambassador to the left of the existing board as well as where they will look for docs / information:

https://app.conceptboard.com/board/mc7s-g0d3-goao-48ey-cmfr

It's probably very wrong with my limited knowledge, so feel free to add comments or suggest changes.

[jenisys]

On the newest release pytest v7, it was mentioned that they also changed the documentation according to divio style. While this only applies partly to README / CONTRIBUTING docs, some parts may be useful there. In addition, these README / CONTRIBUTING docs will point to the other documentation parts, which may reflect this style.

NOTE:
As far as I can tell, the current documentation already uses parts of this documentation style.

SEE ALSO:

• https://documentation.divio.com
• https://docs.pytest.org/en/7.0.x/contents.html
• https://docs.djangoproject.com/en/4.0/#how-the-documentation-is-organized

[luke-hill]

A fair amount of work has been done here recently. Where do we think we're at @ehuelsmann / @mpkorstanje / @davidjgoss @jenisys ?