Comment on page
Style Guide
General Style Guide to follow
In order to keep our documentation consistent across various spaces, we ask that you respect the following conventions and best practices when contributing documentation to the CHAOSS community.
Try to keep your writing clear and concise. Your explanations should be comprehensive, but easy to follow. The more precise your writing is, the easier others will find it to follow.
Here are some general guidelines and reminders for tone and style:
- Write accessibly in clear, simple sentences intended for a global audience.
- Avoid colloquial language, humor, cultural references, and personal opinion. Keep your writing technical.
- Write from a second-person point of view. Use "you" and "your", not "my", "our", or "their".
- Avoid jargon and acronyms, if you can. Spell out acronyms at least once per page.
- Remember to link to glossary terms when first introducing them in a paragraph.
- Be consistent. Use the same consistently-formatted word or phrase for a concept throughout the documentation.
- Don't qualify or prejudge actions. Don't write that something is "easy" or "quick" as this is a deterrent if the user is not able to complete the action.
- Don't reference future development or features that don't yet exist.
- Remember to use sentence case for page titles and section headings.
- Use numbered lists for actions that happen in sequence.
- Use bulleted lists for most other lists.
Source Citation: This page has been taken and inspired by the Atom documentation under the "Writing Style Guide" section https://wiki.accesstomemory.org/wiki/Resources/Documentation/Contribution_guidelines#Writing_style
Last modified 3yr ago