[editorial] Hugo front matter title and other fixes

[chalin]

• Upholds Consistent page title form and capitalization #169
• Prep for [editorial] Inline Hugo front matter #1821
• Fixes the Hugo front matter for all doc pages
• Consistently:
  • Uses Title Case for titles
  • Uses Sentence case for linkTitles (sidenav on OTel.io)
  • Ensures that the linkTitle corresponds to the title. There were a few instance where these did not match.
• Removes **...** bolding from one of the titles.
• Adds and/or fixes path_base_for_github_subdir to ensure that OTel.io users can navigate to the page source
• Drops empty <!--- Hugo front matter ... ---> comments

/cc @trask @open-telemetry/docs-maintainers

[noahfalk]

Looks fine to me. I'm happy to defer to maintainers on the styling.

[joaopgrassi]

Thank you for working on this! I left a few questions I wasn't sure about.

[trask]

thanks for this!

I left a few non-blocking suggestions if they make sense

[lmolkova]

Thanks a lot for doing this!

I hope we could do better in semconv and either automate or at least catch some of these during review.

A few things that could help:

1. Is there a crash course on hugo (in the context of otel.io)? E.g.

   • we have <!--- Hugo front matter used to generate the website version of this page: ---> in some cases we have it in some other cases we don't - why?
   • Is there a good link we could add to contributing.md to help contributors with incantations like path_base_for_github_subdir ?
   • How to rename/move files keeping website links

2. Could we come up with some guidance on how to do things in semconv?
   E.g.

   • linkTitle is a short thing that does not include semconv name, just the sub-area within it. It should usually be Spans, Metrics, Resources, etc. It's in 'Sentence case'
   • Headings should use 'Title Case' (TBH I'd default to `Sentence case' everywhere)

I'm happy to follow up on this, but would probably need help with Hugo part

[trask]

@chalin do you think we need to fix our CI check to accommodate this change? if so, is it possible to split that out into a separate issue so we can go ahead and merge this PR?

diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index 0fe77dd5..fbb3f279 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -1,10 +1,9 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Registry
-weight: -2
-auto_gen: below
 path_base_for_github_subdir:
   from: tmp/semconv/docs/attributes-registry/_index.md
   to: attributes-registry/README.md
+weight: -2
 --->

[chalin]

@chalin do you think we need to fix our CI check to accommodate this change?

Yes, done.

[chalin]

• Headings should use 'Title Case' (TBH I'd default to `Sentence case' everywhere)

@lmolkova - sentence case is my preference as well, and what Google recommends in it's style guide, see Headings:

Use sentence case for headings and titles.

I'd like to land this PR. I can switch to title case if you prefer in a followup PR. In this way both title and link-title will match in their use of letter case. Let me know what you think.

As for your other questions, I'll need to get back to you. Maybe we can track that via a separate issue. (Edit: short answer is that we can certainly document conventions and actually automate some checks.)

[lmolkova]

@chalin sure, let's go ahead with this PR - I created #1834 to track follow ups

[chalin]

@trask @lmolkova - Ok, this PR is ready for a final review and approval. All raised concerns have been addressed.