The mx-bluesky documentation is confusing, misleading and repetitive

[rtuck99]

The below is written against #548 which made some rationalisations, prior to that it is likely even worse.

Some additional comments about the documentation - I think it's still confusing, partly the fault of python copier template. Perhaps in future we should just ignore most of their documentation templates because I think they are not really designed for our use case.

So, if you go to the documentation front page, to look for how to deploy mx-bluesky/hyperion you see this:

ok, so go to the "User Guide"

under installation, this doesn't mention dls_dev_env.sh.

the real documentation is in mx-bluesky/build/html/developer/general/how-to/get-started.html

I think we should delete the installation documentation in the User Guide as generally users won't be installing mx-bluesky themselves either as a development install or a production deployment.

Similarly "Run in a container"

In fact, maybe we should just get rid of the User Guide section entirely as there is nothing in there at the moment for actual users.

Ok, so how about the Developer Guide:

Maybe we should change the title of General MX-Bluesky Developer Guide so we don't have two of them...

So lets try General MX-Bluesky Developer Guide (the first one):

If I'm a developer, the install documentation must be in Developer Install? Wrong!

That's just the generic install documentation

Try Get started with mx-bluesky - at least this tells you to use dls_dev_setup.sh. But wait - it's really called dls_dev_env.sh.

How about General MX-Bluesky Developer Guide (second one)

Under Development Installation this is the same information but at least tells you to use the right script.

There's also this weird section called "hyperion" which is second in the TOC but is actually the introductory overview of the old hyperion project and should really be at the top-level to describe the difference between the mx-bluesky and hyperion portions and also it could probably do with some updating.

We should also combine the running the unit test sections from both halves as it's really one project with different ways of deploying and launching.

tl;dr

• Get rid of User Guide section and move everything up one level, or at least clear it out until we have some documentation for actual users.
• Rename "General MX-Bluesky Developer Guide" to something like"Hyperion Developer Guide"
• Move and update the project overview from inside Hyperion section to the top level
• Update the general developer install and unit test instructions and remove the duplicated hyperion ones