Add style guide and basic contribution section

[theletterf]

• Fixes Style guide for OpenTelemetry documentation (and potentially CNCF) community#1828
• Fixes Add a section to CONTRIBUTING.md about writing/styling guidance #1890
• Fixes Add a "How to Contribute" section to opentelemetry.io #3254

Initial structure and a good chunk of the style guide are taken from the Kubernetes docs site, with adaptations.

Preview:

• https://deploy-preview-3651--opentelemetry.netlify.app/docs/contributing/
• CONTRIBUTING.md

[hdost]

I know it's only in draft but left some comments to call out a couple ideas.

Thank you for taking this on!

[svrnm]

I know it's only in draft but left some comments to call out a couple ideas.

Thank you for engaging in this conversation!

Also, to have this here, copying @chalin's comment (open-telemetry/community#1828 (comment)):

There is a /site section that I created. For now, it contains site-build info, but I've been wanting to use it to host our "site docs". The style guide would fit under there. Just an idea.

[svrnm]

Initial structure and a good chunk of the style guide are taken from the Kubernetes docs site, with adaptations.

So, the structure works for me, although I am not 100% sure about the content of each page:

• We have some content in CONTRIBUTING.md already, so this would need to be migrated as well then and then reduced to something similar to this: https://github.com/kubernetes/website/blob/main/CONTRIBUTING.md
• Some of those pages are fairly extensive already, so we need to go through them 1:1 and decide what we want to carry over and what we want to change, or what we don't want to have (e.g. we have no localization yet, so we need to phrase this differently)
• Especially for the style guide, I would prefer to make this page referencing the K8s documentation and then we add everything that is OTel specific

[chalin]

I strongly second what @svrnm has shared (in the previous comment #3651 (comment)).

[chalin]

Btw, you can probably just replace the mermaid shortcodes by plain fenced code blocks:

```mermaid
...
```

[theletterf]

@chalin Thanks! I'm open to moving the guide, etc. to /site, though right now it doesn't have a menu item. Also, it wouldn't be visible from the docs (unlike K8s), and semantically speaking it seems more concerned with technical aspects than a /docs/contribute directory.

[theletterf]

@svrnm Applied most changes and fixed linter issues. This should now serve as a base for further changes.

[svrnm]

Thank you for the time and effort to write this down @theletterf , here are some suggestions

[theletterf]

Thanks @chalin! I hope we're not letting through anything egregious, copy wise — we've undergone several review rounds already. Fully agree on iterating afterwards.

Re: contribution-guidelines.md, I've chosen to keep it there, as it's not visible in the ToC anyway. I've made some edits to add a link to the new contribution section. What's the purpose of this hidden doc, if I may ask?

On gerunds in headings and such, this PR already aims to apply Google Style Guide's guidance. It's slightly different for file names and directories though, so I've renamed the main folder.

Note: The concurrent mode for link checking is working well!

[chalin]

Re: contribution-guidelines.md, I've chosen to keep it there, as it's not visible in the ToC anyway. I've made some edits to add a link to the new contribution section. What's the purpose of this hidden doc, if I may ask?

That page was created way-back because Docsy requires that file to exist if we use it's default community page content. IIRC, we didn't want to have to fuss with the file, given that #897 had been filed, and so we chose to simply not show it in the left nav.

My preference would be that you remove that file (and ensure that the content is covered elsewhere), though we can do that later if y'all prefer.

There are a few of my originally suggested changes that remain to be done:

Note: The concurrent mode for link checking is working well!

Yes, I'm so glad it works so well 😄

[theletterf]

@chalin Thanks! Comments addressed. Let's remove that file in a later update.

[theletterf]

@svrnm There seem to be an error with links in main related to some spec links. This wasn't in my branch.

Edit: Updated main now and the error disappeared. Thanks!

[chalin]

@chalin Thanks! Comments addressed.

Thanks for following through with those suggested updates.

Let's remove that file in a later update.

Ok, in that case:

• Let's keep Contribution guidelines needs rework or should be dropped #897 open -- i.e., pls remove the "fix" mention in the opening comment
• Drop the change to .htmltest.yml since that assumed you'd be deleting /docs/contribution-guidelines

You'll need to rebase and push (I can't from the web UI):

[chalin]

A comment for later: I don't think that we should duplicate here in the form of a table any checks that the tools do. IMHO, we should just mention the tools and how to invoke them so that contributors know if they're using the proper spelling and capitalization.

[theletterf]

I think there's a strong educational value in having our terminology presented as reference. This is not too different from what style guides do with their wordlists:

• https://developers.google.com/style/word-list
• https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Usagedictionary
• https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/m/microsoft-store

Having a place that explains, for humans, what the proper capitalization or spelling is for OTel terminology also has the potential of ending discussions and preventing headaches during editing.

[chalin]

Thanks for the links. I agree that it can make sense for both the terms OpenTelemetry and OTel, but not e.g. for Repository or simple cases of all caps for acronyms. But we can discuss these finer points later.

Also, if we can automate the creation of such a table somehow, that would satisfy my need to keep things DRY.

[theletterf]

Agree on the generic terminology! Automation would be great, too.

In general, while deeply imperfect, I see this initial PR as the foundation for deeper discussions around our contribution guidelines and style. We'll get to a great point soon, I'm sure!

[theletterf]

See #3846

[theletterf]

@chalin

• Removed the Fix statement for that Contribution guidelines needs rework or should be dropped #897 in the description (resolution would be partial anyway).
• Restored the .htmltest.yml file.
• Merged from main and solved the refcache.json conflict.

[chalin]

Stellar! 🚀

[theletterf]

@svrnm Seems like we can go live! :)

[svrnm]

🎉 https://opentelemetry.io/docs/contributing/