Style guide for OpenTelemetry documentation (and potentially CNCF)

[theletterf]

As I've recently become an approver for OpenTelemetry.io, I discussed with @svrnm the need for a style guide. Little things like "should we capitalize 'Collector' in the docs" can waste precious time when reviewing documentation. This can be solved by using a style guide.

Style guides describe writing, formatting, and editing standards. When used for documentation, they help ensure consistency and facilitate the job of editors, reducing discussions and generally speeding things up. Like coding style guides, prose style guides can be enforced to a certain extent using linters such as Vale or proselint.

Some notable examples of documentation style guides include:

• Microsoft Style Guide
• Google Style Guide
• IBM Style Guide
• Splunk Style Guide

None is superior to others, though adoption rates vary. To have and follow a style guide is better than not having one. Other CNCF projects, like Kubernetes, have a style guide and could contribute, in the future, to a unified CNCF style guide. In the meantime, though, I think the time is ripe for the OpenTelemetry community to decide on the need for a style guide and build one to facilitate documentation production and consistency.

What should the OpenTelemetry style guide include?

As I recently said elsewhere, we should put in our style guide what we'd like our past selves to have known when editing the first documents. More specifically, the style guide should cover, at the very least, the following aspects:

• Usage of words / Terminology, and terms to avoid. For example, should we say "on-premises" or "on-premise"? Do we capitalize "Collector"? When is it appropriate to say "ingest"? And so on.
• Formatting: When to use bold, italic, quotation marks, how to format tables and callouts, etc.
• Style: Tense, voice, pronouns, jargon, when to use callouts and notes, how to format numbers, units of measurement, punctuation, casing in titles, and so on.
• Bias-free and accessible communication, for example the usage of singular they in documentation. See a list here.
• Accessibility: Use of alt text in images and diagrams, avoiding positional language for screen readers ("above"), etc.

Should we adopt an existing style guide, like Google's?

While there's a strong overlap between style guides for documentation, and while Google's is a pretty popular style guide among software developers, I think the OpenTelemetry Style Guide should be an entity on its own and take decisions that are aligned with its community and their sentiment on linguistic matters. Some decisions might align with Google's or others', which makes the process of building the guide slightly faster, but others might diverge. So, in short, no, we shouldn't blindly adopt one unless we feel it applies 100% to our case.

Where should the OpenTelemetry style guide live?

Similar to Kubernetes', the OpenTelemetry Style Guide could live in OpenTelemetry.io and constitute the bulk of the contribution guide. Alternatively, it could be hosted in a separate repository and could be integrated as a content submodule. The repository could also contain rules for prose linters, if developed.

Who should contribute to the style guide?

Everyone, of course. If treated as a project, the style guide would have its own issue tracker and pull requests. All maintainers and approvers of OpenTelemetry.io would contribute to it, but also everyone who's contributing documentation in code repositories. When done collectively, style guides are stronger. I think there should be a steering team, though.

Should this be a CNCF-wide initiative?

I don't know enough of CNCF's governance to answer that, but I reckon that anything related to language and comms should strive to find common ground across CNCF, as style is also a reflection of the product culture and of shared core values. For example, the use of singular "they" is endorsed by many style guides because of its inclusivity. A common style guide would also benefit CNCF-organized events, as it'd provide a framework for keynotes, educational materials, etc.

What's next?

I want to participate in the creation of a style guide for OpenTelemetry.io, but first I'd like to gauge your interest and know your takes on the matter. Let's discuss!

[theletterf]

(Could someone assign this one to me, too? Thanks!)

[svrnm]

Thanks for raising this issue, @theletterf. Although high impact for https://github.com/open-telemetry/opentelemetry.io, this is something relevant for all OTel sub-projects. I even argue that this can help to translate some "this is how we write it" from the spec to the docs, because as of today I can not guarantee that we provide consistent writing even for defined terms.

A few pointers for what we have as of today for https://github.com/open-telemetry/opentelemetry.io: we have introduced a combination of CSpell and textlint to provide some level of style guidance (e.g. K8s, OpenTelemetry, OTel er enforced via that). Although this does not provide us with a style guide in the sense you have outlined it here.

On the topic of having a OTel / CNCF style guide: I am a big fan of implementing one, because it greatly can help to remove some mental burden (how do I write that?) and at the same time accomplish consistency. The first part (the removed mental burden) is even the one which is more important to me: I am not a big fan of bikeshedding¹, so I want something that doesn't make me think. What I mean by that: let's pick something pre-existing (what K8s has²), add the things missing for us and go with it.

Footnotes

1. an term I don't know before contributing to otel ↩

2. this also makes it easier to talk about something broader/CNCF-wide ↩

[tigrannajaryan]

let's pick something pre-existing (what K8s has2), add the things missing for us and go with it.

+1.

[chalin]

+1, I'd vote for adoption of either the Google Style Guide or the Kubernetes Guide; and the allow for (minor) deltas specific to our needs. This would be a great starting point.

[svrnm]

+1, I'd vote for adoption of either the Google Style Guide or the Kubernetes Guide; and the allow for (minor) deltas specific to our needs. This would be a great starting point.

If I remember correctly the K8s guide is not covering all the things (e.g. how to write certain words), so we should have both and could do it in that way: OTel specific rules -> K8s style guide -> Google Style Guide

[theletterf]

I'll see if I can draft something. How do you feel about publishing it on the site itself and linking to it from CONTRIBUTING?

[chalin]

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.