Website: Update docs style guide with community style guide

[zacharysarah]

Feature request

What would you like to be added?

The K8s community style guide grew out of the SIG Docs style guide. The community guide has since added guidelines that would make excellent additions to the SIG Docs style guide. For example: the K8s community has excellent guidelines for link formatting.

Why is this needed?

It's important to keep our style guide fresh, accurate, and synchronized with best practices in the K8s community.

Comments

Because style guides have a large impact, the PR author should expect lengthy and extensive review with multiple rounds of feedback.

A PR that resolves this issue should:

• [ ] Determine which guidelines from the K8s community style guide will improve the SIG Docs style guide.
• [ ] Invite review from stakeholders across the community, including @kubernetes/community-maintainers and @kubernetes/sig-docs-en-owners.

/good-first-issue
/sig docs
/cc @parispittman @nikhita @mrbobbytables

[k8s-ci-robot]

@zacharysarah:
This request has been marked as suitable for new contributors.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-good-first-issue command.

In response to this:

Feature request

What would you like to be added?

The K8s community style guide grew out of the SIG Docs style guide. The community guide has since added guidelines that would make excellent additions to the SIG Docs style guide. For example: the K8s community has excellent guidelines for link formatting.

Why is this needed?

It's important to keep our style guide fresh, accurate, and synchronized with best practices in the K8s community.

Comments

Because style guides have a large impact, the PR author should expect lengthy and extensive review with multiple rounds of feedback.

A PR that resolves this issue should:

• [ ] Determine which guidelines from the K8s community style guide will improve the SIG Docs style guide.
• [ ] Invite review from stakeholders across the community, including @kubernetes/community-maintainers and @kubernetes/sig-docs-en-owners.

/good-first-issue
/sig docs
/cc @parispittman @nikhita @mrbobbytables

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[DanRoscigno]

I would like to work on this issue.

[zacharysarah]

@DanRoscigno Feel free to open a PR, even just a placeholder to get started.

One tip: if you include the words fixes #14101 or closes #14101 in the original description, GitHub automatically closes this issue when the PR merges.

[DanRoscigno]

As I work through comparing the two guides I will check off the boxes. Unchecked items are missing from the SIG Docs guide.

List of topics in the community guide which appear in the SIG Docs guide:

Design / Format / Language:

• [ ] Contact info
• [ ] Date / Time
• [ ] Diagrams / Images / other assets
• [x] Doc layout
• [x] Text formatting
• [x] Language / Grammar / Tone
• [ ] Guidelines around inclusive language (Note: This is included in Language in the Community guide)
• [ ] Moving a doc (maybe this fits elsewhere, it is about use of git-mv)
• [ ] Punctuation (yay Oxford comma!)
• [ ] Quotes

Markdown

• [ ] Code blocks
• [x] Emphasis
• [x] Headings
• [ ] Horizontal rules
• [ ] Line length
• [ ] Links
• [ ] Lists
• [ ] Metadata
• [x] Tables

[DanRoscigno]

As I dig in deeper to the templates, content organization, and Hugo shortcode pages I expect to find some of the unchecked items. More in a bit.

[zacharysarah]

@aimeeu Another good place to start

[DanRoscigno]

@aimeeu I did a little research, ping me here and I can catch you up. I have been out of town for a few weeks on an assignment and not looked at this in a while!

[aimeeu]

@DanRoscigno thanks! I’m on vacation until Monday, 5 August. I’ll ping you next week.

[aimeeu]

/assign aimeeu

[sftim]

/kind feature
/priority backlog

[jaypipes]

@zacharysarah hey, so are there specific PRs for this Issue that you'd like reviewed? or are you just looking for feedback on the overall list of tasks you want to get done?

[zacharysarah]

@jaypipes This issue is probably more complicated than can be reasonably accomplished in a sprint.

This issue will probably require a series of iterative PRs. Feedback is also welcome!

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[sftim]

/remove-lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.