Move documentation from the docs repo

[aslakhellesoy]

Description

Document Cucumber Expressions in the same repo where their implementation lives.

Motivation & context

• Your docs belong in the code repository
• Discussion around general improvements of the documentation docs#633
• Improve READMEs and CONTRIBUTING documents common#1521

Update required of cucumber.io/docs

Ref: cucumber/docs#667

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[olleolleolle]

Are we using American or British English as our target language? (US color+recognize vs UK colour+recognise.)

[aslakhellesoy]

I think British English is the predominant language used in our docs, but I’m sure there are many inconsistencies.

[olleolleolle]

This is such a good idea.

[aurelien-reeves]

What about moving Grammar and "Production rules* paragraphs elsewhere?
Those are far more technical, maybe in a CONTRIBUTING.md or ARCHITECTURE.md document?

[olleolleolle]

Off-topic, but grammar-related: When this morning I visited the README, I wondered, "this grammar notation, what language is that written in?"

[mpkorstanje]

Parts of this documentation - specifically the how-to-do-in-language-x - aren't quite part of this cucumber expressions module. The module only provides a registry. Would it be an idea to link to the relevant sections in the Cucumber implementation read me's for those parts?

[aslakhellesoy]

I had the same thought @mpkorstanje and decided to leave here for now since some of the cucumber implementations don’t (yet) have a github markdown page we can link to.

I’d prefer to do that in a second pass, which would involve creating a ticket in all the relevant repos, and wait for these tickets to be resolved.

[aslakhellesoy]

Off-topic, but grammar-related: When this morning I visited the README, I wondered, "this grammar notation, what language is that written in?"

It’s pseudo-EBNF

[olleolleolle]

Off-topic, but grammar-related: When this morning I visited the README, I wondered, "this grammar notation, what language is that written in?"

It’s pseudo-EBNF

Perfect. Then this makes it perhaps-more-legible: #10