gcg/static-cms
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
static-cms/website/content/docs/writing-style-guide.md

261 lines
5.4 KiB
Markdown
Raw Normal View History

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
2019-07-24 16:30:10 -05:00
---
title: Writing Style Guide
weight: 30
feat(docs): docs settings, group values, post summaries, weight sorting (branch updated) (#4280)
2020-09-09 04:38:48 -07:00
group: Contributing
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
2019-07-24 16:30:10 -05:00
---
# 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:
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
```
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
2019-07-24 16:30:10 -05:00
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
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: A _collection_ is a set of entries …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: A "collection" is a set of entries …
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
2019-07-24 16:30:10 -05:00
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: These components form the _control pane_.
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
2019-07-24 16:30:10 -05:00
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.
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Go to the `/docs/guides` directory.
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
2019-07-24 16:30:10 -05:00
Don't: Go to the /docs/guides directory.
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Open the `/admin/index.html` file.
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
2019-07-24 16:30:10 -05:00
Don't: Open the /admin/index.html file.
_____
### Use the international standard for punctuation inside quotes
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Branch names begin with "cms".
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
2019-07-24 16:30:10 -05:00
Don't: Branch names begin with "stage."
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: The copy is called a "fork".
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
2019-07-24 16:30:10 -05:00
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 (`).
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: The `yarn start` command starts the development server.
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
2019-07-24 16:30:10 -05:00
Don't: The "yarn start" command starts the development server.
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: For a production build, use `yarn build`.
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
2019-07-24 16:30:10 -05:00
Don't: For a production build, use "yarn build".
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Enclose code samples with triple backticks. `(```)`
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
2019-07-24 16:30:10 -05:00
Don't:Enclose code samples with any other syntax.
_____
### Use code style for object field names
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Set the value of the `media_folder` field in the configuration file.
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
2019-07-24 16:30:10 -05:00
Don't: Set the value of the "media_folder" field in the configuration file.
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: The value of the `name` field is a string.
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
2019-07-24 16:30:10 -05:00
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.
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Set the value of `publish_mode` to editorial_workflow.
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
2019-07-24 16:30:10 -05:00
Don't: Set the value of `imagePullPolicy` to "Always".
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Set the value of `image` to nginx:1.8.
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
2019-07-24 16:30:10 -05:00
Don't: Set the value of `image` to `nginx:1.8`.
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Set the value of the `replicas` field to 2.
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
2019-07-24 16:30:10 -05:00
Don't: Set the value of the `replicas` field to 2.
_____
## Code snippet formatting
### Don’t include the command prompt
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: yarn start
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
2019-07-24 16:30:10 -05:00
Don't: $ yarn start
## Content best practices
This section contains suggested best practices for clear, concise, and consistent content.
### Use present tense
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: This command starts a proxy.
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
2019-07-24 16:30:10 -05:00
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
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: You can explore the API using a browser.
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
2019-07-24 16:30:10 -05:00
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.”
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: To create an entry, …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: In order to create an entry, …
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
2019-07-24 16:30:10 -05:00
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: See the configuration file.
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
2019-07-24 16:30:10 -05:00
Don't: Please see the configuration file.
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: View the fields.
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
2019-07-24 16:30:10 -05:00
Don't: With this next command, we'll view the fields.
_____
### Address the reader as “you”
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: You can create a Deployment by …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: We'll create a Deployment by …
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
2019-07-24 16:30:10 -05:00
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: In the preceding output, you can see…
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: In the preceding output, we can see …
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
2019-07-24 16:30:10 -05:00
### Avoid Latin phrases
Prefer English terms over Latin abbreviations.
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: For example, …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: e.g., …
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
2019-07-24 16:30:10 -05:00
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: That is, …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: i.e., …
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
2019-07-24 16:30:10 -05:00
_____
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.
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Version 1.4 includes …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: In version 1.4, we have added …
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
2019-07-24 16:30:10 -05:00
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Netlify CMS provides a new feature for …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: We provide a new feature …
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
2019-07-24 16:30:10 -05:00
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: This page teaches you how to use Widgets.
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
2019-07-24 16:30:10 -05:00
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
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: Under the hood, …
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
2019-07-24 16:30:10 -05:00
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: Create a new cluster.
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
2019-07-24 16:30:10 -05:00
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
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Avoid words like “currently” and “new.” A feature that is new today will not be new in a few months.
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: In version 1.4, …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: In the current version, …
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
2019-07-24 16:30:10 -05:00
_____
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Do: The Federation feature provides …
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
2019-07-24 16:30:10 -05:00
feat(test): add docs linter to PR workflow actions (#4321)
2020-10-11 07:02:47 -07:00
Don't: The new Federation feature provides …
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
2019-07-24 16:30:10 -05:00
_____
Reference in New Issue Copy Permalink