Merge pull request #154 from miharp/feat/modernize-contributing

Modernize CONTRIBUTING.md for OpenVox

Author: tuxmea

CONTRIBUTING.md

@@ -1,88 +1,75 @@
+# Contributing to OpenVox Documentation
 
-We welcome community contributions to the documentation! You can help by reporting errors and typos, or by contributing new or updated sections. This topic describes the two main ways to contribute to the docs, and provides guidance on writing good documentation.
+We welcome community contributions to the OpenVox documentation! You can help by reporting errors and typos, or by contributing new or updated content.
 
-## Two ways to improve the Puppet documentation
+## Reporting issues
 
-### Filing a ticket
+File a [GitHub issue](https://github.com/OpenVoxProject/openvox-docs/issues) to report errors, inaccuracies, or gaps in the documentation. Include:
 
-The Puppet documentation is managed like a software project, and you can file bug reports and feature requests in its
-[issue tracker](https://tickets.puppetlabs.com/browse/DOCUMENT). You'll need to create a [JIRA account](https://tickets.puppetlabs.com/secure/Signup!default.jspa) if you don't already have one.
+- The URL of the affected page
+- A description of what is wrong or missing
+- Your best understanding of what the documentation _should_ say
 
-In your ticket, provide as much information as possible about what's missing, what's inaccurate, or what's outdated. Include URLs to the affected pages. Describe your best understanding of what the documentation _should_ say. We'll begin looking into the problem, and you can follow our progress in the ticket.
+## Contributing changes
 
-### Emailing us
+Contributions are made via GitHub pull requests.
 
-If you spot a typo or other minor error and don't want to go through the overhead of filing a ticket or editing the documentation, you can report it by email to <docs@puppet.com>.
+1. [Fork the repository](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) and create a branch from `master`
+2. Make your changes (see [Previewing locally](#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:
 
-## Puppet documentation guidelines
+- **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](https://developercertificate.org/)
 
-If you'd like to help contribute edits or new topics to the documentation, use these guidelines to create your content and then attach it when you file a ticket, either in the body of the ticket or as a separate markdown or text file.
+The `Signed-off-by` trailer must match your Git identity:
 
-### Writing new topics from scratch
+```text
+Signed-off-by: Your Name <your@email.com>
+```
 
-Each topic file should cover a single subject area. If the Puppet docs already have topics that discuss this area, modify those existing topics rather than creating a new one.
+## Previewing locally
 
-If you're writing a new topic, start with an overview:
+Ruby 3.2 or later is required. With [rbenv](https://github.com/rbenv/rbenv) or [rvm](https://rvm.io/) installed:
 
-- Provide definitions and descriptions that introduce the subject and place it within the context of the rest of Puppet.
-- Provide diagrams if they help clarify relationships and structures. 
-- Your goal is to help people solve problems and get things done. Avoid too much background information.
+```bash
+bundle install
+bundle exec jekyll serve
+```
 
-Next, describe things that the person *does*:
+The site is available at `http://localhost:4000`. Navigation changes require updating the matching file in `_data/nav/`.
 
-- Create a section for each major task that a person does. These should describe how to get results people want, not just things the tools require them to do.
-- List prerequisites, if any. 
-- Use a numbered list to list the actions the person does to accomplish the task. 
-- Finish by stating what the outcome is, and what the person might do next. 
-- Provide code or command examples that show what to do for common scenarios.
-- If there are multiple ways of doing something, describe only one: the most straight-forward way for the given context. 
-- Use screen captures minimally (ideally not at all), and only to illustrate things that are otherwise impractical to describe. 
-- Avoid mixing lengthy conceptual descriptions in with task steps. Put those in your overview section instead.
+## Writing guidelines
 
-For reference information for a command line tool or an API, follow the layout patterns in similar existing Puppet documentation. If this is lengthy, split it into its own Markdown file.
+### Writing and editing pages
 
-Provide links to related Puppet documentation topics, or other resources.
-
-### Updating existing documentation topics
-
-Sometimes our docs are missing useful information that you can provide:
-
-- Basic-level concepts the original author took for granted, but are helpful for new people
-- Missing overviews, steps, or links
-- Missing prerequisites for tasks
-- Clarifying definitions for terms that Puppet is using differently than other technologies (for example, "class")
-- Helpful code or command line examples
-- Troubleshooting tips
+- 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
 
-- Strive to be friendly and authoritative.
-- Use simple, direct language. Avoid passive voice and implications.
-- Be consise, but not terse.
-- Use second-person almost always: "Open the file in your favorite text editor."
-- Use inclusive, gender-neutral language.
-- Avoid patronizing language, often indicated by words like _clearly_, _actually_, or _obviously_.
-- Be honest but not negative about our product or competitors.
-
-### Grammar, idiom, and spelling
-
-- Metaphors, analogies, and certain turns of phrase might not translate into languages or cultures other than your own. Stick to comparisons that are relatively innocuous and universal.
-- Almost always, follow Associated Press (AP) Style and choose [Webster's dictionary](http://www.merriam-webster.com/) spelling (American): _color_, _specialize_.
-- Use the serial comma. In a list with three or more items, include a comma after the second-last item, before the conjunction: "... is supported on Unix, Linux, and Windows."
-
-### Headings
+- 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_
 
-Use headings to increase the scanability of your content, and to make separate sections for conceptual information, each task, and reference information. 
+### Grammar and spelling
 
-- Nest H3s (markdown: `### `) inside H2s (`## `). Nest H4s (`#### `) inside H3s. 
-- For conceptual information, use a noun phrase that accurately describes the content (for example, "Defined resource types"). 
-- For task section headings, use a verb phrase that indicates the goal (for example, "Deploying your code"), but also differentiates it from other tasks (so maybe, "Deploying your code to a test environment").
+- Follow the [Google developer documentation style guide](https://developers.google.com/style) 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
 
-- For file names and directories, use `monospace`.
-- When citing text that appears in the GUI, use **bold**.
-- For commands and code examples, use `monospace`. Short commands can be included as part of the paragraph. Longer examples or code should be set in a separate paragraph, enclosed within three tildes (`~~~`).
-- For user input on the command line, use `monospace`. For user input on a GUI, use _italics_.
-- To indicate text in code that should be replaced, use angle-brackets and all-caps (and, if in a code example, monospace): `<TEST_HOSTNAME>`
+- 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.)