We hope that you will consider contributing to the Solidus documentation.
We want to provide the Solidus community with consistent, easy-to-read, and easy-to-maintain articles. If you decide to submit a pull request, please try to follow the guidelines listed here.
- Prefer U.S. spelling.
- Prefer short, simple sentences that are under 12 words long.
- Avoid using English-language idioms. Many idioms are challenging for non-native English speakers . ("The configuration is simple," not "The configuration is a piece of cake.")
- Avoid using jargon English like "e.g." and "i.e." Write out a phrase like "for example" instead.
- Avoid words that have multiple meanings (or homographs ), especially when the meanings may be technical. For example: using the phrase "For instance" to reference an example might be confused for an instance of an object.
- Use GitHub Flavored Markdown for article content.
- Break lines when they reach 80 characters unless the characters are a URL or Markdown table-formatted lines.
- Prefer [full reference links][full-references-links] to inline Markdown links. Full reference links are easier to maintain in the long term.
- Use bold and italic text sparingly.
- Mark text that appears in a GUI using bold text.
Grammar and capitalization
- Use the Oxford comma in lists. (Peanuts, cashews, and almonds.)
- Use sentence-style capitalization for article titles. ("Asset management", not "Asset Management".)
- Use sub-headings to help readers quickly scan and understand the content.
- If a list is longer than three items, break it into bullet points.
- Prefer to write in the present tense. The present tense is simpler and easier to read .
- Do not abbreviate terminal commands. (
bundle exec rails server, not
bundle exec rails s.)
- Put filenames, paths, and single-word references to code in
inlinecode elements. ("Use the
paymentsmethod to get a list of payments.")
- Use fenced code blocks for any amount of example code.
- Describe what the code in each fenced code block does in the text above it.
Solidus is an open source platform supported by the community. We encourage everyone using Solius to contribute back to the documentation and the code.