dwave-hybrid
dwave-hybrid copied to clipboard
dwavesystems
Ref workflows on RTD
Currently https://docs.ocean.dwavesys.com/projects/hybrid/en/stable/reference/reference.html mixes workflows and dimod samplers without clear distinction; for example:
- workflow:
- sampler:
What do you think about moving the dimod samplers to https://docs.ocean.dwavesys.com/projects/hybrid/en/stable/reference/samplers.html and clearly stating that workflows are workflows in the description; e.g., "An opinionated hybrid asynchronous decomposition sampler for problems of arbitrary structure and size" --> "An opinionated hybrid asynchronous decomposition workflow for problems of arbitrary structure and size. "
I don't think dimod samplers should live in the page with hybrid samplers (workflows).
Dimod samplers that wrap hybrid workflows/samplers can all trivially be replaced with hybrid.HybridSampler around the workflows, and they exist merely for convenience to users used to dimod samplers.
I believe documentation should group entities by function, not syntax. Hence, Kerberos workflow sampler and Kerberos dimod sampler should sit next to each other. Similarly for PT, PA, etc.
Going with your preference, we should at least make that clearly stick out - I was scrolling down and at first I thought it was a mistake that Kerberos was repeated. We want non-expert users to find it simple to plug in Kerberos as a minimum-thought sampler and for such users the differences on the RTD page might be a bit subtle.
Maybe it's enough to just link to it from the intro page, when you introduce the kerberos sampler?
Would be nice to also to add at least a few signpost statements for users scrolling through the Reference Workflows page that the next item is a sampler. dwave-hybrid has a lot of components with its internal terminology for new users to absorb, I expect some to come here without having the difference between a workflow, hybrid sampler, and dimod samplers at the front of their minds.