docs
docs copied to clipboard
dwavesystems
Feature request: "best current practices" page
As the Ocean toolkit grows, you'll likely have a problem that has affected us in the Rosetta community: documentation for older protocols persists, and it can be difficult for a new user to pick out the best current practices. A page organized by tasks that a user might want to perform, indicating the best current way to accomplish the task, followed by a list of older ways that are clearly marked as older, would be very useful. (Note that I have not exhaustively explored the Ocean documentation. It is possible that this already exists.)
@vmullig, thank you for sharing your Rosetta experience with us and proposing this feature. We too experience the ongoing problem of new users relearning lessons that more experienced users, including especially D-Wave researchers, have already worked their hard way through. The intention of the system document https://docs.dwavesys.com/docs/latest/doc_handbook.html is to always provide the current best practices in using the D-Wave system and formulating suitable models, and problems to be aware of (which might be somewhat equivalent in our context to older protocols). Please take a look at it.
The Ocean documentation needs to point this out more clearly. We are currently working on improving the integration of our documentation. A harder problem is keeping the need to report new best practices for documentation in the minds of our users--perhaps you have some helpful experience to share on solving that? :-)
The intention of the system document https://docs.dwavesys.com/docs/latest/doc_handbook.html is to always provide the current best practices in using the D-Wave system and formulating suitable models, and problems to be aware of (which might be somewhat equivalent in our context to older protocols). Please take a look at it.
Looking through that, it looks like exactly the sort of thing that I was looking for. Apologies -- I hadn't dug deeply enough.
A harder problem is keeping the need to report new best practices for documentation in the minds of our users--perhaps you have some helpful experience to share on solving that?
Unfortunately, it's a problem for us in the Rosetta community too. The problem is compounded by the fact that, when you have a complex system with many applications, no single person has expertise on the best practices for all of the use cases, so we can't have a single person whose job it is to keep the best practices documentation up to date. But we have learnt a few lessons about managing big complicated scientific software projects over 15+ years and keeping them accessible to new users. My colleague, Julia Koehler Leman, is in the process of revising a "lessons learnt" review article about the software development, testing, documentation, and sustainability process which I could send you down the road. It might be useful.