Standardisation of sphinx docs page titles

[callumforrester]

This may be the nitpickiest issue I have ever raised, so should not be actioned unless there's strong agreement.

(from https://diamondlightsource.github.io/python-copier-template/main/how-to.html)

It annoys me that the titles for docs pages are not really standardised, Some Are Capitalised, some are not, some are prefixed with "How to" or similar. If there is a really easy check that can be added to the docs builds it might add a layer of consistency and professionalism. The hardest part, as ever when we talk about formatting, may be agreeing on which standard to use.

[DiamondJoseph]

I'd remove any "how tos", make everything sentence case, make everything imperative tone, remove any specific names (Sphinx, Excalidraw).

This then becomes

Set up developer environment
Build docs
Check docs style
Contribute to the template
Check code coverage
Embed diagrams
Lint automatically
Lock requirements
Make a release
Set up publishing
Add images
Run tests
Run static analysis
Enable strict linting
Update to the latest template

[coretl]

https://diataxis.fr/how-to-guides/#pay-attention-to-naming suggests keeping "How to" in the title.

Agree with the rest of it

[DiamondJoseph]

Grumble grumble

How to set up developer environment
How to build docs
How to check docs style
How to contribute to the template
How to check code coverage
How to embed diagrams
How to lint automatically
How to lock requirements
How to make a release
How to set up publishing
How to add images
How to run tests
How to run static analysis
How to enable strict linting
How to update to the latest template

Just seems... repetitive

[callumforrester]

Isn't it being in the "How-to" section enough?

[coretl]

Is that too bad?

[DiamondJoseph]

I must admit variable multiple lines and not in monospace font does make it look less horrid for sure

[GDYendell]

I think the titles should be phrased such that they could be (and implicitly are) prepended with "How to...", but don't actually include it.

[coretl]

I'm still going to argue that "How to" should be in the title, because then every time you reference it the title for the link will begin "How to", as will the page title in google...

[callumforrester]

The hardest part, as ever when we talk about formatting, may be agreeing on which standard to use.

...

Anyone for rock, paper, scissors?

[GDYendell]

I'm still going to argue that "How to" should be in the title, because then every time you reference it the title for the link will begin "How to", as will the page title in google...

Yeah OK, this is a good point...

[callumforrester]

Do we want other prefixes for the other sections?

[coretl]

Do we want other prefixes for the other sections?

https://diataxis.fr/start-here/ doesn't seem to. I'm not sure if it is clear from just the titles if they are tutorials or not?

[callumforrester]

Just having them for how-tos seems more confusing but not too strongly opposed.

I'm still going to argue that "How to" should be in the title, because then every time you reference it the title for the link will begin "How to", as will the page title in google...

Having thought about it a bit more I don't really agree with this. Once you click a link you can clearly see that the page is in the "How To" section. There can also be context around the link and if you're Googling something you know you're trying to figure out how to do it. As an aside I have a pet peeve about Youtube tutorial videos that open with "Hi guys, today we're going to learn how to do XYZ". I know we are, I'm the one who googled it, get on with it!

I can't actually think of a realistic scenario where someone would click the link if it said "How to XYZ" and would not click the link if it didn't.

[coretl]

It's Monday morning and I don't have the energy to argue, so I'll accept a PR either way as long as it's consistent.