Feedback: 'NServiceBus sagas: Saga basics'

[BenHughesTPR]

Feedback for 'NServiceBus sagas: Saga basics' https://docs.particular.net/tutorials/nservicebus-sagas/1-saga-basics/

Location in GitHub: https://github.com/Particular/docs.particular.net/blob/master/tutorials/nservicebus-sagas/1-saga-basics/tutorial.md

Naming convention of Policy is inconsistent with other documentation/examples: https://docs.particular.net/nservicebus/sagas/#a-simple-saga

[andreasohlund]

Thanks for the feedback @BenHughesTPR

Docs like https://docs.particular.net/nservicebus/sagas/#a-simple-saga that speak about the feature itself, ie a "Saga" where the target audience is developers we want to be explicit and name things in a way that makes the most sense in that context, MySaga etc etc

In the tutorials, which are meant to be more like "real code in a business project" we tend to want to use names that are likely to be meaningful to the fictive business people. "Policies" is something that sagas are a great fit when it comes to implementation but when talking to the business the word "Saga" is likely not something they have in their vocabulary so talking about a ShippingPolicy vs a ShippingSaga would likely make it that conversation easier.

ShippingPolicySaga might be an option but I prefer the simpler name since that is what will show up in visualizations like the ServiceInsight saga view.

Also, the developers will still know it's a saga since ShippingPolicy implements Saga<T> when reading the code.

I know this is quite a bit of a personal opinion here, what do U think?

[BenHughesTPR]

Hi Andreas, thanks for your response - I'm coming from the perspective of someone brand new to NServiceBus, so I'm working through each of the tutorials right now. I do like how opinionated NServiceBus is, but I think that comes with a real need for consistency, so seeing different naming in different places threw me off a bit.

I think the thing we're always striving for is that ubiquitous language that developers and business owners can speak, so my suggestion would be to maybe have a naming best practices section in the documentation here: https://docs.particular.net/nservicebus/sagas/#a-simple-saga. Then it could contain some guidance on when a saga is best called a policy or a workflow, or whatever language best captures the underlying business context.