[editorial] Ensure every docs folder has a README?

[chalin]

This is the semconv version of:

• [editorial] Ensure every section has a README opentelemetry-specification#2558

Some folders are missing README.md files:

$ ls -R $(find docs -type d '!' -exec test -e "{}/README.md" ';' -print)
docs/cli:
cli-spans.md

docs/dns:
dns-metrics.md

docs/graphql:
graphql-spans.md

docs/non-normative/groups:
system

docs/non-normative/groups/system:
design-philosophy.md    use-cases.md

When folders don't have a readme, the pages it contains will appear in the left nav rooted in the closest ancestor with a readme. Are you ok with that? Here are the semconv pages as currently published: https://opentelemetry.io/docs/specs/semconv/

For folders containing more than one file, a README.md should be added that lists the folder content.

For folders containing a single file could simply be renamed to README.md or a README.md can be added. WDYT?

[trask]

I think I like the lack of additional nesting when not needed:

as opposed to URL, which has a mostly empty README, and leads to:

[chalin]

Yes, I agree. Though, when there is more than one entry in a folder, it should probably have a README. (That could be checked.)

Might be good to remove the README for the "URL" section?

[trask]

when there is more than one entry in a folder, it should probably have a README

👍

Might be good to remove the README for the "URL" section?

#1860

[joaopgrassi]

Given the URL page was fixed, do we have still something to do here?

[chalin]

when there is more than one entry in a folder, it should probably have a README. (That could be checked.)

Add a check remains, either via this issue or another. I'm not sure I'll have time to work on this soon (FYI).