Expand style guide - Githubissues

steveperry-53 commented 6 years ago

This is a...

[x] Feature Request
[ ] Bug Report

Problem: The current documentation style guide is missing some key information.

The current style guide has some guidelines that I would like to revisit.

Proposed Solution:

Add more guidance in these areas:

Use of bold and italics We say things like "Use bold for user-interface elements." But we don't go on to say "Don't use bold for anything else." Should our style guide say things like "Don't us bold for general emphasis."? Or "Don't use bold for anything except ..."? Same question for italics.

We say to use italics to introduce a term. I figure that meant to italicize the term when you introduce it, but not every time it appears on the page. Do we need to spell this out? Here's an example of a new topic that goes a little crazy with italics: Service Catalog.
Use of glossary terms We don't have guidance about how to use glossary terms, but I think we should. Here's a new topic that I think goes overboard with underlined glossary terms: Service Catalog. I think we should have a guideline like this: Use a glossary tag on first mention of a term. Possibly use same glossary tag once for each major section of the document. But don't use the same glossary tag every time a term appears. While we're at it, should we say something like, "Don't capitalize a glossary term just because it's a glossary term". See Service Catalog for weird capitalization of glossary terms.

And another thing. We have this capitalization thing built in to some of our glossary definitions:
```
Service Catalog provides a way to list, provision, and bind with external {% glossary_tooltip text="Managed Services" term_id="managed-service" %} from {% glossary_tooltip text="Service Brokers" term_id="service-broker" %} without needing detailed knowledge about how those services are created or managed.
```
Use of quotes Should our style guide provide guidance about using quotes? For example, do we want to say something like "Don't use quotes to introduce a term. Use italics instead."? Or "Avoid air quotes."?
Word choice Should our style guide have a section on word choice? Examples: Use "may" for permission and "might" for possibility. Don't use "since" as a replacement for "because".
Crisp language Our style guide already has a section called Use simple and direct language. We give these examples:
- Use "to" instead of "in order to".
- Use "See" instead of "Please see".
- Use "View the Pods" instead of "With this next command, we'll view the Pods".
Do we want to expand the list of examples of simple and direct language. For example:
- Use "in" instead of "within".
Capitalization of Node The style guide says to use camel casing for Kubernetes API objects. And we don't try to distinguish between the generic and the specific. For example, we always use Pod, not pod, even if the we're talking generically about the Pods in a cluster. The idea is that it would get too complicated to try to distinguish between the generic and the specific. According to that guideline, we should always use Node, not node ("io.k8s.api.core.v1.Node"). Is the current guideline what we want? Or should we revise the guideline to include generic use of things like nodes?

Revisit these areas:

Address the reader as "you"
Don't use "we"
Jargon and idioms
Latin phrases

Bring the style guide into alignment with itself.

Example: The copy is called a "fork" should be The copy is called a fork.

Page to Update: https://kubernetes.io/docs/home/contribute/style-guide/

heckj commented 6 years ago

:+1: sounds good to me

jesscodez commented 6 years ago

These guidelines make sense overall. Though I was guilty of breaking quite a few of them in the app developer user journey, I revised most violations before thet PR merged. (A few "air quotes" did slip through.)

That being said, I think that the rule around bolded text warrants more discussion. Doc writers should be able to use bold for visual effect, not just for GUI elements. When readers are scrolling quickly through a page, bold helps them easily pick out the terms or phrases that are important.

There's potential for over-bolding, but we can use the style guide to caution people to use their best judgment.

bradtopol commented 6 years ago

I think the proposed improvements and desire to revisit certain areas would be very helpful

Bradamant3 commented 6 years ago

I see @abiogenesis-now's point about wanting emphasis. But it's all too common to wind up with too much bold on the page. And it loses its effectiveness in displaying names of GUI elements. Do we have any other options for emphasis?

jesscodez commented 6 years ago

I'm not sure what styling would be best, but I'm also okay with creating a special CSS class---having to write <span class="special-styling">Text</span> creates enough of a barrier for entry that it won't be overused (?)

Bradamant3 commented 6 years ago

I'd also like to see us think not just about revising the guidelines, but also about promoting them more effectively. We could provide some small-scale enforcement with a doc linter like vale, but maybe we also need to think about ways to explain more specifically what we mean by some of the writing recommendations we make (as opposed to the markup recommendations) -- that is, the items in the current style guide listed under Content best practices and Patterns to avoid (https://kubernetes.io/docs/home/contribute/style-guide/#content-best-practices).

We could also brainstorm ways to take the style guide back to the rest of the community. Part of the sig-docs-to-other-sigs initiative, and the docs training as part of Paris's mentoring program -- although we should probably get better alignment in practice within sig-docs itself before we take things out to a larger group.

That said, we do need to consider what makes sense to try to enforce.

steveperry-53 commented 6 years ago

Thanks everybody. Keep those comments coming. I've been looking over the new user journeys content. I see fairly consistent use of things that go against our style guide. So I think it's important for us to discuss this and come to agreement.

Here's just one example. The phrase "we'll show ...", goes against two of our current guidelines: Use present tense, and don't use "we".

steveperry-53 commented 6 years ago

To answer the question about options for emphasis: The style guide has a section on Callout Formatting.

heckj commented 6 years ago

Where was the “we’ll show” phrase? I was expecting I was probably the one that violated that style guideline, as I have a tendency to use it informally to build a sense of companionship with the reader. I totally get WHY we don’t want to use it, so I tried to not use it - that said, I didn’t spot it in a quick look. We may not have caught it on the updates/edits.

steveperry-53 commented 6 years ago

Here's a "we'll get". https://kubernetes.io/docs/user-journeys/users/cluster-operator/intermediate/

Seems like I've spotted other cases of "we'll". Not sure it's worth hunting them all down right now.

Here's a "will introduce". https://kubernetes.io/docs/user-journeys/users/cluster-operator/foundational/

heckj commented 6 years ago

Heh - it was me, I suspected it might be. I’ll take a pass re-reading that whole set and make the relevant updates to match our style guide. Thank you

steveperry-53 commented 6 years ago

/lifecycle frozen