Request: better/centralized documentation on syntax

[jlumpe]

Most of the documentation in the "Defining Workflows" section is organized on the basis of goal or use case. This works but I feel it is also very important to have a some sort of a reference page that documents all syntax elements in a single place. A couple of really good examples of this are the documentation pages for Dockerfiles and GitHub Actions workflows.

This sort of exists in the "Writing Workflows" page with the EBNF grammar, but this is difficult to read and doesn't describe what any of it does. I don't think a whole lot would be needed here, just a few sentences for each thing and then it could link to other parts of the documentation that go into more detail.

I'd be willing to submit a PR to get the ball rolling on this if it's something that would be wanted.

[jlumpe]

Possible duplicate of #1168

[corneliusroemer]

Great idea to improve docs. By the way, the EBNF grammar in docs is outdated, see #2224

[johanneskoester]

Hi. Thanks for the suggestion! Sure, any documentation improvement is highly appreciated, and I am happy to merge corresponding PRs.