The landing/index pages for samples are overwhelming

[kbaley]

This issue was transferred from a private repository

We have a ton (180ish) of great samples but the experience for finding them isn't great. I think that spending some time cleaning up this area of the docs website will help users (and us) to find and take advantage of relevant samples.

If you go to https://docs.particular.net/samples/ you get:

• A long page that contains a bunch of information that most people probably don't care about. If I click on a link in a menu that says "Samples" I am probably not looking for this document. In some ways this document reads like a samples policy. Maybe it should be pulled out as a separate document and linked to from every sample (/included in every sample download package)
  • There is a link to the step-by-step sample at the top of the page but it's easy to miss in the wall of text
  • There is also a link to a list of samples but this just replicates the menu without any kind of styling or additional info. Maybe just a list of categories (preferably matching the sequence in the main menu (Messaging, Transports, Persistence, Platform)) would be helpful. Highlighting the showcase and monitoring demos here could be helpful as well.
• The General section of samples
  • General has become a bit of a dumping ground for any sample that doesn't fit anywhere else. Currently, the top 3 samples I see are FileShare Attachments, SQL Attachments, and AuditFilter. The first 3 samples I should see should be something like: Creating an endpoint, Sending a message, Handling a message. It might be worth introducing a new Basic/Beginner category to try and tidy this up. I think the individual samples are ordered by directory name but as that doesn't have to match the sample name it leads to a very confusing menu.
  • Those first 3 samples I see are demonstrating community projects. This helps to blur the line between what is supported and what is not
• An automatically generated (and confusing) menu
  • The menu appears to be ordered on directory name but that name does not have to match the sample (or category) name.
    • The main menu is mostly alphabetical but NServiceBus.Bridge and NServiceBus.Wormhole are not under N, they are under B and W
    • In General, we have the following order:
      • Entity Framework integration
      • Automatic Retries
      • Fault Tolerance
      • Building a Custom Feature
      • File Share DataBus Usage

I would also consider adding a "Samples" menu link at the bottom of each technology-specific section of the main menu (so under Transports->SQL Server there would be an entry for Samples). I know each page has a related samples section but I think this would make it much easier to navigate to the samples I am looking for.

[tamararivera]

The multi topic task force for DevEd, analyzed this issue and here are our conclusions so the next team can take them in consideration.

• with the removal of the last community project samples, the left site menu should be ordered alphabetically
• it is technically possible to prevent the engine to create the list of samples, we need to add 'suppressRelated: true' to the headers of the index page. But we didn't move ahead with this because it seems there is no agreement on what should we show on this page, or what it is used for.
  Also, we noticed that the left side menu doesn't start expanded when you visit that page, and it is probably related to the fact that it expects that the url matches with one of the sub headers (samples is the only header that has a page), and also why you can't navigate to the page using the left sidebar.