Add docs for where to put dodal logic

[olliesilvester]

Fixes #617

Instructions to reviewer on how to test:

1. run tox -e docs autobuild and read the docs added
2. Furiously debate the wording

After writing this I noticed a very similar section in ophyd-async https://blueskyproject.io/ophyd-async/main/explanations/where-device-logic.html . This dodal page is more diamond specific, but I'm perhaps it's better to delete the overlap?

Checks for reviewer

• Would the PR title make sense to a scientist on a set of release notes
• If a new device has been added does it follow the standards
• If changing the API for a pre-existing device, ensure that any beamlines using this device have updated their Bluesky plans accordingly
• Have the connection tests for the relevant beamline(s) been run via dodal connect ${BEAMLINE}

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.06%. Comparing base (56091f0) to head (03d3bb3).
Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1250      +/-   ##
==========================================
+ Coverage   97.98%   98.06%   +0.07%     
==========================================
  Files         199      203       +4     
  Lines        7686     7788     +102     
==========================================
+ Hits         7531     7637     +106     
+ Misses        155      151       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[olliesilvester]

I think I should probably also include something about when composite devices. Perhaps: if a group of devices would only ever be used together, and never individually, then a composite device is suitable.

[DominicOram]

Furiously debate the wording

I will try and avoid this as much as possible, that being said...

We already have information like this at:

• https://diamondlightsource.github.io/dodal/main/how-to/create-device.html
• https://diamondlightsource.github.io/dodal/main/reference/device-standards.html#where-to-put-devices

Can we either make sure it's linked or, ideally put it all on the one page and avoid repetition.

[DominicOram]

Should: There is a missing category here. Where it is affects multiple devices but is not experiment specific. e.g. changing the energy for the DCM, whilst keeping the Undulator gap correct. We have done this in UndulatorDCM but could have used a plan. The reasoning for a device was:

• It takes time and we have no way of running concurrent plans but we do for concurrent device sets
• It's low level and experiment/beamline agnostic

I think there is debate to be had here though

[olliesilvester]

I think this category is my number 4, maybe I wasn't clear on the "multiple devices" part though.

I was going to include that you could make a composite device in this case too, but I know there are still some differing opinions there. To me, my above comment

Perhaps: if a group of devices would only ever be used together, and never individually, then a composite device is suitable.

covers most cases, and I agree with you that not being able to write parallel plans is another good reason to use a device composite.

[DominicOram]

Sure, I think put that in then. It's ok for docs to say "this is an option to think about in this case but it's very usecase dependant"

[olliesilvester]

I think linking to the ophyd async docs covers a lot of what I had written, but hopefully the new flowchart helps. There is still a bit of repetition in the how to guide for creating a device, but I don't think it's too bad - it goes into more detail