Particular
Feedback: 'Configuration'
Feedback for 'Configuration' https://docs.particular.net/transports/azure-service-bus/configuration
Location in GitHub: https://github.com/Particular/docs.particular.net/blob/master/transports/azure-service-bus/configuration.md
SubscriptionNameShortener, SubscriptionRuleNamingConvention and RuleNameShortener are confusing for those unfamiliar with the underlying transport technology and don't want to deal with Azure Service Bus official documentation that is not the easiest to digest.
See this Twitter thread.
Thanks, @SeanFeldman. What type of improvement do you suggest? Do you think that having a better explanation of what each Func<> accepts and is expected to return is a good improvement?
From the thread, the highlighted pain points indicated that the following would be helpful:
- Elaborating on what the offered transport API is achieving
- Provide guidance for the most common practices when using the transport
Personally, I think it goes beyond this transport and likely applies to other transports/persistences. I will note that I do not agree with documenting the underlying technology. Just as RabbitMQ or Storage Queues should not be documented, the same applies to Azure Service Bus. Also, adding guidance vs documenting APIs are apples to oranges.
If I would go about this change, I would address #1 by expanding on what each API is achieving and coving the callback arguments and returned types. It is a bit cryptic. For #2 I would have a separate 'common scenarios' or 'points for consideration' section/page.