Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a style guide to documentation contributor info #1632

Closed
cory-wc opened this issue Aug 20, 2018 · 7 comments
Closed

Add a style guide to documentation contributor info #1632

cory-wc opened this issue Aug 20, 2018 · 7 comments
Labels
event: Write the Docs Suggested issues for Writing Day contributors at Write the Docs Portland 2019 status: stale

Comments

@cory-wc
Copy link
Contributor

cory-wc commented Aug 20, 2018

Is your feature request related to a problem? Please describe.
The Contributor Guides do not reference a style guide for the documentation. I'm not certain how to appropriately document things without creating major style/voice inconsistencies.

Describe the solution you'd like
Create a style guide that's available through the documentation Contributor Guide, or determine one that can be replicated.

Describe alternatives you've considered

Additional context
I found the style guide for the Kubernetes docs useful: https://kubernetes.io/docs/contribute/style/style-guide/#use-bold-for-user-interface-elements.

Related issues
Issue 1038

@kurtgcollins
Copy link
Contributor

I'd be interested in contributing to this. Do we want to just reference a larger, more well known style guide with some exceptions?

@verythorough
Copy link
Contributor

Nice suggestion for using the Kubernetes guide, @cory-wc

I think the only rule I don't really like in it is Use normal style for string and integer field values, but even then I don't really see it as worth making an exception for.

I think linking to Kubernetes's style guide from the contributor guide would be a great start. What do you think, @kurtgcollins?

@kurtgcollins
Copy link
Contributor

@verythorough - I agree that the Kubernetes guide looks pretty good. I think we could add a few more things for readability's sake, such as sentence length, but the Kubernetes guide is a great start.

@erquhart
Copy link
Contributor

I'd only add that the Kubernetes guide feels like a lot - we should try to make ours feel less so.

@verythorough verythorough added the event: Write the Docs Suggested issues for Writing Day contributors at Write the Docs Portland 2019 label May 16, 2019
@MimiDumpling
Copy link

Hello! I'll start a Markdown file and make a PR to get this started. 😸

@stale
Copy link

stale bot commented Oct 29, 2019

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

@martinjagodic
Copy link
Member

Apparently done in #2336

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
event: Write the Docs Suggested issues for Writing Day contributors at Write the Docs Portland 2019 status: stale
Projects
None yet
Development

No branches or pull requests

7 participants