LogoLogo
  • CHAOSS Community Handbook - Table of Contents
  • Handbook Usage
  • ABOUT
    • CHAOSS History
    • Values
    • Roadmap
    • Roles and Responsibilities
    • Community Guidelines
    • Path to Leadership
    • Terminology
      • CHAOSS Specific Terms
      • CHAOSS Committees
      • CHAOSS Community Working Group Terminology
      • CHAOSS Community Mentorship Terminology
    • Terminology Usage
    • General FAQ
  • COMMUNITY
    • Working Groups
      • WG Repository Structure
    • Metrics
      • Releases
      • Translation
      • Metrics FAQ
    • Community Report
    • CHAOSScon
    • CHAOSScast
    • CHAOSS Meetings
  • CONTRIBUTING
    • Development
      • Contributing Workflow
    • Documentation
      • Style Guide
    • Design
      • Design Workflow
      • Design Contribution
      • CHAOSS Visual Identity
    • Outreach
  • MENTORSHIPS
    • Google Summer of Code
    • Google Season of Docs
    • GSoC/GSoD Roles & Responsibilities
    • Outreachy
  • D&I BADGING
    • Overview of the D&I Badging
    • How to contribute
    • Apply for a badge
      • Apply for an In-Person Event
      • Apply for a Virtual Event
    • Reviewing for CHAOSS
      • Apply to Review
      • The Review Process
      • Conflict of Interest Policy
    • Badging Roles
      • Applicant
      • Reviewer
      • Moderator
      • Maintainer
    • The badging-bot
    • D&I Badging Code of Conduct
Powered by GitBook
On this page

Was this helpful?

Export as PDF
  1. CONTRIBUTING
  2. Documentation

Style Guide

General Style Guide to follow

PreviousDocumentationNextDesign

Last updated 4 years ago

Was this helpful?

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