Unfortunately, good code won't speak for itself. Even the most elegantly designed and well-written codebase that solves the most pressing problem in the world won't just get adopted on its own. You, the open-source creator, need to speak for your code and breathe life into your creation. That's where technical writing and documentation come in. (Source credit: Kevin Xu's article on from opensource.com)

We encourage documentation contribution from everyone and generally, that contribution is divided into two categories:

• General improvements: typo corrections, fixing broken refs or links, correcting inaccurate or out-of-date information, and offering better explanations through clearer writing and additional examples.

• New features or new pages: Adding a page of documentation that we haven't yet covered in our ongoing attempt for completeness, or documenting a new feature that has been added to CHAOSS projects since the last release.

Getting Started

We don't have any specific space for documentation. Most of the documentation you will find inside the CHAOSS GitHub repositories and on the website.

Approach to Contribute

• Addressing issues related to documentation: Look for the documentation labeled issues within the CHAOSS Github repositories.

• Checking if a page needs to be updated: Surf around the CHAOSS community, look for the pages that need to be updated, and suggest changes through an issue or pull request.

• Propose new pages for the documentation: While working on CHAOSS initiatives and software you might come across documentation needs; Open an issue to remember for later and ask for help or create a pull request to add the documentation yourself.

Once you have figured the approach below is the flow you need to follow:

• Open the CHAOSS GitHub and find the repository on which you want to contribute. (Assume the governance repository here; using the GitHub.com user interface.)

• Click on the file you want to edit. For instance, I have taken the README.md file. Click on the pencil option to edit the page.

• Make any edits you need, remembering to always format them using Markdown. To understand Markdown better, check out the GitHub reference or GibtBook reference guides.

• When you are done making changes, scroll down, and write a short description of your changes. Select the option Create a new branch for this commit and start a pull request and click on Propose file change. This will direct you to the Pull request page.

• On the Pull Request page, write the description of your changes and create a pull request by clicking on create pull request button

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.