Improve the structure of the docs

[mpkorstanje]

Currently the structure of the cucumber docs is rather confused. Content with different goals is grouped together. This makes for a poor first user experience and a rather confused second user experience. This can be improved by changing the structure and rewriting the articles to conform to one of the types of docs below:

Types of docs

• Start here / Getting started
  Like the Getting Started document I mentioned previously, this is the place where you tell users what they need to know before they even get started.
• Reference guide/Glossary
  The reference guide is comprehensive and usually pretty dry. This is where terms are defined, functions' input and output are explained, and examples are given. The tone is factual and to the point. There's not much discussion, or conversation. The voice is usually impersonal.
• Tutorials
  Tutorials hold your hand and lead you down the path. They show you each step, and occasionally sit down on a bench by the path to explain the rationale for a particular step. They are very conversational, sometimes even chatty. The voice is personal; you are speaking to a particular person, defined in the earlier persona phase.
• Learning/understanding
  Often linked to from the tutorials, the learning/understanding documents dig deeper. They investigate the why and the how of a particular thing. Why was a certain decision made? How was it implemented in the code? What does the future look like for this thing? How can you help create that future? These documents are sometimes better done as blog posts than as part of the formal documentation, as they can be a serious distraction to people that are just trying to solve a problem.

Structure

With this in mind the structure should be

• Cucumber Open Docs welcome page
  • What is Cucumber Open? (introduction)
  • How to use this documentation (for different types of users)
  • How to Get Started button/link (for new users)
  • List of platforms/cucumbers? Somehow clarify that there are different languages/implementation.
• Getting started
  • Installation
  • 10-minute tutorial (maybe we should make it more BDD-cycle like)
  • TODO: Tutorial on how to add Cucumber to existing project
  • Link to Cucumber School
  • Link to additional docs useful for learning
  • Related tools
• Learning/understanding
  • Testable architecture
  • ?? Anti-patterns? / Links to blog posts
  • Writing better Gherkin
  • Helpers/ / Helper method
  • Organizing step definition
• Cucumber Reference
  • Features Gherkin Reference)
  • Scenarios (Gherkin Reference)
  • Steps (Gherkin Reference)
  • Step Definitions
  • Cucumber Expressions
  • Regular Expressions
  • Hooks
  • Sharing state / The world object
  • Configuration
• Reporting & Formatters
  • How-to guides
  • Integration with tool X (TODO) - ? What about current Tools section?)
  • API automation
  • Browser automation
• Glossary
• Help
  • FAQ
  • FAQ related tools
  • Get in Touch
    • Slack
    • GitHub
    • Forum
  • Community
    • Contributing
    • Contributing to docs
    • Community blogposts -> find relevant sections for any that are relevant.
    • Professional services -> Clean up and keep books, rename and maybe move section
    • Sponsors
  • Team -> remove (DONE in issue-474/remove-teams #536)

Fix some issues:

• Language tabs should look like tabs: Missing background for language tabs #426
• Fix links under Docs > Change links under "Docs" menu on https://cucumber.io/docs #433
• Direct links to menu items: Direct links no longer available #434
• We should make sure that the top 5-10 links accessed from outside redirected to the new page

@mlvandijk @gasparnagy @danascheider

[mpkorstanje]

A few examples to compare against:

https://www.rust-lang.org/learn

https://kotlinlang.org/docs/reference/

[mlvandijk]

Hacktoberfest update:
Partial PRs for any of the improvements listed above would be very welcome!
Please make sure a partial PR does not close this issue.

[pattimcletchie]

@mlvandijk @mpkorstanje is this available to pick up? I'd be happy to work on it.

[mlvandijk]

Absolutely! We'd love your help.
You're welcome to pick up even a part of it. It would be helpful to let us know which part you're starting on, in case someone else wants to work on this too.

[pattimcletchie]

@mlvandijk I can remove the teams page & the introduction page.

[mlvandijk]

@pattimcletchie Sure, go ahead! Let me know if you need any help. :)