Learning Samples don't offer clues about ideal Next Steps for each transport

[kbaley]

trafficstars

This issue was transferred from a private repository

We have great learning samples. Frequently when people get to the end of those samples the next step they take is to try and evolve the sample to use a technology that they are interested for. This is where they run into minor differences with the way that these different technologies work.

For instance:

• MSMQ and SQL require registering publishers
  • They also require a different persistence as the learning persistence doesn't support message-driven pub/sub
• MSMQ requires explicit error queue configuration
• RabbitMQ and Azure Service Bus requires selection of a topology
  • The Azure Endpoint Oriented Topology requires publisher registration
• Most of the transports require some kind of connection string
• The SQS Transport requires some environment variables

We do throw meaningful exceptions for each of these but it's a frustrating experience to make a change, interpret an error, fix it, and repeat, until finally everything is working again.

What if we had a Next Steps section at the bottom of the last page of the sample that includes links off to things like "Convert to MSMQ", "Convert to SQL Transport", etc. Each of these documents can be short checklists of the things that need to be done with links off to the relevant documentation.

If there is evidence that people are following these breadcrumbs, then we can look at other doing the same for persistence (which also can have some technology-variation based speed bumps).

This documentation might belong in the Learning Transport (and Learning Persistence) docs. Samples that use the Learning Transport can include a standard block that says "Migrate this sample to a different transport and persistence" with appropriate links to the right places.

[kbaley]

Some work on this was started on https://github.com/Particular/docs.particular.net/pull/4349

[kbaley]

Here's one idea of a kind of wizard that directs users to a "getting started" configuration for their specific environment: https://github.com/VerifyTests/Verify/blob/main/docs/wiz/readme.md. We could offer a similar kind of mechanism that asks users what their transport, persister, serializer, hosting, etc, environment is and then give them specific guidance and configuration code for it.