WTD19: Improve Contrib Guide and Create Style Guide (#2336)
* getting started with the contributor guide updates for Netlify CMS at WTD19PDX * places to get involved header * create/mimi-style-guide initial commit * added guide for new terms * completed Documentation Formatting Standards * starting headings and content for contributing guidelines * added guide for inline code and commands * added guide for object field names * added guide for string and integer field values * added guide for code snippet formatting * added content best practices * Updated contributor guide * added guide for Patterns to avoid. Also added Note at the top * Update contributor-guide.md * Update and rename style-guide.md to writing-style-guide.md
This commit is contained in:
Jeremy Meiss
Shawn Erquhart
parent
24b0330621
commit
7fb1168f24
@ -1,11 +1,31 @@
|
||||
---
|
||||
title: Contributor Guide
|
||||
weight: 100
|
||||
weight: 20
|
||||
group: contributing
|
||||
---
|
||||
|
||||
We're hoping that Netlify CMS will do for the [JAMstack](https://www.jamstack.org) what WordPress did for dynamic sites back in the day. We know we can't do that without building a thriving community of contributors and users, and we'd love to have you join us.
|
||||
|
||||
## Getting started with contributing
|
||||
Being a developer is not a requirement for contributing to Netlify CMS, you only need the desire, a web browser, and a [GitHub account](https://github.com/join). The GitHub repo has a step-by-step [guide](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) to get started with the code.
|
||||
|
||||
## The basics of the Netlify CMS docs
|
||||
The documentation for Netlify CMS is written in [Markdown](http://daringfireball.net/projects/markdown/) (a good cheatsheet on Markdown is [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)), with the source residing on [GitHub](https://github.com/netlify-cms) in the `/website/content/docs` folder.
|
||||
|
||||
The GitHub website allows you to submit issues, work with files, search for content, and browse changes that have been submitted in the past and those that are being submitted now (aka Pull Requests).
|
||||
|
||||
## Style guidelines
|
||||
A [style guide](/website/content/docs/style-guide.md) is available to help provide context around grammar, code styling, syntax, etc.
|
||||
|
||||
## Filing issues
|
||||
If you have a GitHub account, you can file an [issue](https://github.com/netlify/netlify-cms/issues) (aka bug report) against the Netlify CMS docs. Even if you're not able to, or don't know how to, fix the issue (see [Improve existing content](#improve-existing-content)), it helps to start the conversation.
|
||||
|
||||
When filing an issue, it is important to remember the [Code of Conduct](https://github.com/netlify/netlify-cms/blob/master/CODE_OF_CONDUCT.md).
|
||||
|
||||
## Improve existing content
|
||||
If you are able to offer up a change to existing content, we welcome this. Once you've forked the repo, and changed the content, you would file a pull request (PR). The repo [Contributing file](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) lays out the correct format for PRs.
|
||||
|
||||
## Other places to get involved
|
||||
While we work on building this page (and you can help!), here are some links with more information about getting involved:
|
||||
|
||||
* [Setup instructions and Contribution Guidelines](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md)
|
||||
|
||||
261
website/content/docs/writing-style-guide.md
Normal file
261
website/content/docs/writing-style-guide.md
Normal file
@ -0,0 +1,261 @@
|
||||
---
|
||||
title: Writing Style Guide
|
||||
weight: 30
|
||||
group: contributing
|
||||
---
|
||||
|
||||
# Netlify CMS Style Guide
|
||||
_Adapted from the [Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide)_
|
||||
|
||||
## Documentation Formatting Standards
|
||||
|
||||
### Use angle brackets for placeholders
|
||||
|
||||
Use angle brackets for placeholders. Tell the reader what a placeholder represents.
|
||||
|
||||
1. Display information about a cli command:
|
||||
|
||||
```
|
||||
npm install <package-name>
|
||||
```
|
||||
|
||||
where `<package-name>` is the name of a package.
|
||||
|
||||
### Use bold for user interface elements
|
||||
|
||||
Do: Click **Save**.
|
||||
|
||||
Don't: Click "Save".
|
||||
_____
|
||||
|
||||
Do: Select **Log Out**.
|
||||
|
||||
Don't: Select 'Log Out'.
|
||||
_____
|
||||
|
||||
### Use italics to define or introduce new terms
|
||||
|
||||
Do: A _collection_ is a set of entries ...
|
||||
|
||||
Don't: A "collection" is a set of entries ...
|
||||
_____
|
||||
|
||||
Do: These components form the _control pane_.
|
||||
|
||||
Don't: These components form the **control pane**.
|
||||
_____
|
||||
|
||||
### Use code style for filenames, directories, and paths
|
||||
|
||||
Do: Open the `config.yaml` file.
|
||||
|
||||
Don't: Open the config.yaml file.
|
||||
_____
|
||||
|
||||
Do: Go to the `/docs/guides` directory.
|
||||
|
||||
Don't: Go to the /docs/guides directory.
|
||||
_____
|
||||
|
||||
Do: Open the `/admin/index.html` file.
|
||||
|
||||
Don't: Open the /admin/index.html file.
|
||||
_____
|
||||
|
||||
### Use the international standard for punctuation inside quotes
|
||||
|
||||
Do: Branch names begin with "cms".
|
||||
|
||||
Don't: Branch names begin with "stage."
|
||||
_____
|
||||
|
||||
Do: The copy is called a "fork".
|
||||
|
||||
Don't: The copy is called a "fork."
|
||||
_____
|
||||
|
||||
## Inline code formatting
|
||||
|
||||
### Use code style for inline code and commands
|
||||
|
||||
For inline code in an HTML document, use the `<code>` tag. In a Markdown document, use the backtick (`).
|
||||
|
||||
Do: The `yarn start` command starts the development server.
|
||||
|
||||
Don't: The "yarn start" command starts the development server.
|
||||
_____
|
||||
|
||||
Do: For a production build, use `yarn build`.
|
||||
|
||||
Don't: For a production build, use "yarn build".
|
||||
_____
|
||||
|
||||
Do: Enclose code samples with triple backticks. `(```)`
|
||||
|
||||
Don't:Enclose code samples with any other syntax.
|
||||
_____
|
||||
|
||||
### Use code style for object field names
|
||||
|
||||
Do: Set the value of the `media_folder` field in the configuration file.
|
||||
|
||||
Don't: Set the value of the "media_folder" field in the configuration file.
|
||||
_____
|
||||
|
||||
Do: The value of the `name` field is a string.
|
||||
|
||||
Don't: The value of the "name" field is a string.
|
||||
_____
|
||||
|
||||
### Use normal style for string and integer field values
|
||||
|
||||
For field values of type string or integer, use normal style without quotation marks.
|
||||
|
||||
Do: Set the value of `publish_mode` to editorial_workflow.
|
||||
|
||||
Don't: Set the value of `imagePullPolicy` to "Always".
|
||||
_____
|
||||
|
||||
Do: Set the value of `image` to nginx:1.8.
|
||||
|
||||
Don't: Set the value of `image` to `nginx:1.8`.
|
||||
_____
|
||||
|
||||
Do: Set the value of the `replicas` field to 2.
|
||||
|
||||
Don't: Set the value of the `replicas` field to 2.
|
||||
_____
|
||||
|
||||
## Code snippet formatting
|
||||
|
||||
### Don’t include the command prompt
|
||||
|
||||
Do: yarn start
|
||||
|
||||
Don't: $ yarn start
|
||||
|
||||
## Content best practices
|
||||
|
||||
This section contains suggested best practices for clear, concise, and consistent content.
|
||||
|
||||
### Use present tense
|
||||
|
||||
Do: This command starts a proxy.
|
||||
|
||||
Don't: This command will start a proxy.
|
||||
|
||||
Exception: Use future or past tense if it is required to convey the correct meaning.
|
||||
|
||||
### Use active voice
|
||||
|
||||
Do: You can explore the API using a browser.
|
||||
|
||||
Don't: The API can be explored using a browser.
|
||||
_____
|
||||
|
||||
Do: The YAML file specifies the collection name.
|
||||
|
||||
Don't: The collection name is specified in the YAML file.
|
||||
_____
|
||||
|
||||
Exception: Use passive voice if active voice leads to an awkward construction.
|
||||
|
||||
### Use simple and direct language
|
||||
|
||||
Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”
|
||||
|
||||
Do: To create an entry, ...
|
||||
|
||||
Don't: In order to create an entry, ...
|
||||
_____
|
||||
|
||||
Do: See the configuration file.
|
||||
|
||||
Don't: Please see the configuration file.
|
||||
_____
|
||||
|
||||
Do: View the fields.
|
||||
|
||||
Don't: With this next command, we'll view the fields.
|
||||
_____
|
||||
|
||||
### Address the reader as “you”
|
||||
|
||||
Do: You can create a Deployment by ...
|
||||
|
||||
Don't: We'll create a Deployment by ...
|
||||
_____
|
||||
|
||||
Do: In the preceding output, you can see...
|
||||
|
||||
Don't: In the preceding output, we can see ...
|
||||
|
||||
### Avoid Latin phrases
|
||||
|
||||
Prefer English terms over Latin abbreviations.
|
||||
|
||||
Do: For example, ...
|
||||
|
||||
Don't: e.g., ...
|
||||
_____
|
||||
|
||||
Do: That is, ...
|
||||
|
||||
Don't: i.e., ...
|
||||
_____
|
||||
|
||||
Exception: Use “etc.” for et cetera.
|
||||
|
||||
## Patterns to avoid
|
||||
|
||||
### Avoid using “we”
|
||||
|
||||
Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.
|
||||
|
||||
Do: Version 1.4 includes ...
|
||||
|
||||
Don't: In version 1.4, we have added ...
|
||||
_____
|
||||
|
||||
Do: Netlify CMS provides a new feature for ...
|
||||
|
||||
Don't: We provide a new feature ...
|
||||
_____
|
||||
|
||||
Do: This page teaches you how to use Widgets.
|
||||
|
||||
Don't: In this page, we are going to learn about Widgets.
|
||||
_____
|
||||
|
||||
### Avoid jargon and idioms
|
||||
|
||||
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
|
||||
|
||||
Do: Internally
|
||||
|
||||
Don't: Under the hood, ...
|
||||
_____
|
||||
|
||||
Do: Create a new cluster.
|
||||
|
||||
Don't: Turn up a new cluster.
|
||||
_____
|
||||
|
||||
### Avoid statements about the future
|
||||
|
||||
Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.
|
||||
|
||||
### Avoid statements that will soon be out of date
|
||||
|
||||
Avoid words like “currently” and “new.” A feature that is new today might not be considered new in a few months.
|
||||
|
||||
Do: In version 1.4, ...
|
||||
|
||||
Don't: In the current version, ...
|
||||
_____
|
||||
|
||||
Do: The Federation feature provides ...
|
||||
|
||||
Don't: The new Federation feature provides ...
|
||||
_____
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user