Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
75 lines (51 loc) · 2.93 KB

CONTRIBUTING.md

File metadata and controls

75 lines (51 loc) · 2.93 KB

Contributing to OpenVox Documentation

We welcome community contributions to the OpenVox documentation! You can help by reporting errors and typos, or by contributing new or updated content.

Reporting issues

File a GitHub issue to report errors, inaccuracies, or gaps in the documentation. Include:

  • The URL of the affected page
  • A description of what is wrong or missing
  • Your best understanding of what the documentation should say

Contributing changes

Contributions are made via GitHub pull requests.

  1. Fork the repository and create a branch from master
  2. Make your changes (see Previewing locally below)
  3. Commit with a GPG signature and DCO sign-off: git commit -S -s
  4. Open a pull request against master
  5. Ensure CI is passing and your branch is up to date with master before marking ready for review

All commits must be:

  • GPG-signed (-S): configure a signing key with git config user.signingkey YOUR_KEY_ID and git config commit.gpgsign true
  • DCO signed-off (-s): certifies your contribution under the Developer Certificate of Origin

The Signed-off-by trailer must match your Git identity:

Signed-off-by: Your Name <your@email.com>

Previewing locally

Ruby 3.2 or later is required. With rbenv or rvm installed:

bundle install
bundle exec jekyll serve

The site is available at http://localhost:4000. Navigation changes require updating the matching file in _data/nav/.

Writing guidelines

Writing and editing pages

  • Prefer editing existing pages over creating new ones
  • Each page should cover a single subject area
  • Focus on helping people solve problems and get things done; avoid excessive background
  • Use numbered lists for sequential steps; state prerequisites upfront and the outcome at the end
  • Provide command or code examples for common scenarios
  • Link to related documentation

Tone

  • Be friendly and authoritative
  • Use simple, direct language; avoid passive voice
  • Be concise, but not terse
  • Use second person: "Open the file in your editor"
  • Use inclusive, gender-neutral language
  • Avoid patronizing words like clearly, actually, or obviously

Grammar and spelling

  • Follow the Google developer documentation style guide for general conventions
  • Use American English spelling: color, specialize
  • Use the serial comma: "... supported on Unix, Linux, and Windows"
  • Avoid idioms or metaphors that may not translate across languages and cultures

Formatting

  • File names and paths: monospace
  • Commands and code: monospace; short commands inline, longer blocks in fenced code blocks with a language identifier (bash, yaml, text, etc.)