Menu refactoring about docs HOT 9 CLOSED

This is more streamlined. More focused on getting started. That is good. The BDD section feels out of place.

from docs.

Since this will be docs.cucumber I am (personally) expecting (subject appropriate) in depth technical information. How do I do X? How does Y work? What are the options for Z? By the time people get here they'll have at least been sold on cucumber as a viable concept.

from docs.

PR has been merged and questions answered/solved

from docs.

~ Attempt to make an overview of open questions:

Documents:

• Add a general introduction to "Documents" page (where to go for what?) See #116
• where to place Ruby specific docs currently available See overview in #25
• where to place content not related to Java/JavaScript/Ruby (as current polyglot pages include only those 3 languages) Discussed with @aslakhellesoy : Focus for the docs is on Java/Javascript/Ruby for now.
• would like to find a place for other docs we've worked on (like assertions and mocking-and-stubbing) UPDATE: Discussed with @aslakhellesoy - these can go under "Guides"
• would like to find a place for documents regarding help/support (get-in-touch, contribute, contribute-to-docs) => possibly another menu-item "Help"/"Support"/Community" with subpages, or Adding all of that stuff as an About menu after the search bar
  Note: Most of these are currently inaccessible in the new menu structure.
  UPDATE: Added to "Support", which has also been renamed to "Community"
• Add a recommended media page, as suggested in #48. This should find a place in the docs alongside the blog-posts (not sure where yet; possibly related to Help-section Update: moved to cucumber-website
• Add a FAQ page, as suggested in #52 - while I agree the docs themselves should be as clear as possible, I still see a lot of the same questions pop up regularly either in Slack / other support channels or on StackOverflow. Having a FAQ page might help, if only to point to relevant sections. Update: Nice to have, not needed before publishing
• Rename upgrading.md to versioning.md? Update: no longer relevant

Menu:

• ~~Order of the topics under the Documentation menu: it contains an overview (obivous to start), some on Installation / Running / Configuration, Gherkin, and Step Definition/Hooks/Tags. Some are more about how to write specs/tests (Gherkin -> Step definitions), some more about how to run them (Install/Run/Configure/ and using Hooks and Tags) => What would be the most intuitive order for those topics? ~~ Discussed with Aslak and updated accordingly.

Structure (overall):

• For some pages, we need to shift the structure, so that the entry in @aslakhellesoy menu links to an overview page with a list of links. This way we would get 2 layers: a high level overview straight from menu, and more detailed page accessible from there.

from docs.

This has taken me an unfeasibly long time, partially because I think we're trying to make the single top menu do too much work.

Comparing to something like this https://docs.gradle.org/4.5/userguide/userguide.html which has the top menu (which a similar split) as well as a sub menu on the left and the in page toc on the right.

from docs.

I'm still kicking content around to try to make it work, and whatever I'll document some suggestions here soon.

from docs.

Based on conversation between @plaindocs and myself, we came up with the following tentative structure. Feedback welcome!

• Cucumber

• Overview
• Getting Started (10 min Tutorials - Java/JavaScript/Ruby)
• Gherkin Reference
  • spoken-languages.md
• Cucumber Reference
  • Step Definitions
  • step-argument-transforms.md
  • Hooks
  • Tags
  • Installation
  • Running
  • Config
  • environment-variables.md
  • cucumber.yml.md
  • checking-assertions.md
  • wire-protocol.md
  • content/architecture/execution.md
  • upgrading.md (rename to versioning?)

• Guides

  • BDD
    • Overview
    • BDD Tutorial
    • Example mapping
    • Who does What
    • TDD (content/tdd-introduction.md)
  • Best Practices (content/best-practices.md)
    • content/browser-automation.md
    • content/testable-architecture.md
    • continuous-integration.md
    • mocking-and-stubbing-with-cucumber.md
    • state.md

• Support

  • get-in-touch.md
  • (FAQ #52 )
  • contributing.md
  • contributing-to-documentation.md
  • content/voting.md

• About (could be footer)

  • blog-posts.md
  • (recommended media #48 )
  • projects-using-cucumber.md
  • related-tools.md

Open questions:

• What to do with information about implementations not in Java/JavaScript/Ruby?
• Add a general introduction to "Documents" page (an overview of what to find where on the site?)
• How to implement the second level (marked with + signs):

• We could either add a second menu on the left (like in Gradlel)
• OR we could structure it so the landing pages for Integrations is basically a list of links

from docs.

Do we have any idea why people come to the site? My assumption would be either (possible) new users curious about Cucumber (so provide them with easy overview of what cucumber is and how to get started), or people who use Cucumber and have specific questions so are looking for the "Cucumber reference". Thinking about use cases might help evaluate structure.

from docs.

Considering the docs are going to replace the current docs as part of the website, maybe we should (also) consider them as part of the whole and we what goes where.
I agree with @mpkorstanje that the reference docs should contain the more in depth information. Maybe the Guides should be a separate menu item on the website (for example like https://spring.io/) This would make it easy to add more (How to) Guides in addition to the 10 minute Getting Started later (if we want / can).
The Support information does not need to be part of the docs but relevant info could be added to current Support page.
And BDD should maybe be an item on the website (possibly combined with Cucumber School / BDD kickstarter?)

from docs.