Docs help our customers understand how to use workflows and fix their own problems.
Doc changes are checked for spelling, broken links, and lint issues by CI. To check locally run
- Explain when you would want to use a feature.
- Provide working examples.
- Use simple short sentences and avoid jargon.
- Format code using back-ticks to avoid it being reported spelling error.
- Avoid use title-case mid-sentence. E.g. instead of "the Workflow", write "the workflow".
- Headings should be title-case. E.g. instead of "and", write "And".
To test/run locally:
Use a service like Grammarly to check your grammar.
Having your computer read text out loud is a way to catch problems, e.g.:
- Word substitutions (i.e. the wrong word is used, but spelled. correctly).
- Sentences that do not read correctly will sound wrong.
On Mac, to set-up:
- Go to
System Preferences / Accessibility / Spoken Content.
- Choose a System Voice (I like
Siri Voice 1).
To hear text, select the text you want to hear, then press option+escape.