Skip to content

Latest commit

 

History

History
71 lines (54 loc) · 2.84 KB

CONTRIBUTING.md

File metadata and controls

71 lines (54 loc) · 2.84 KB
Raw

Contributing Guidelines

We love your input! We want to make contributing to Semaphore documentation as easy and transparent as possible.

All currently planned tasks are filed as issues within this repository. Issues are categorized using a small set of labels that correspond to sections of the documentation website. All changes go through a standard pull request process.

Ways to contribute

  1. Reporting errors, something not being clear enough, or expected information missing — open a new issue;
  2. Discussing the current state of content — open a new issue;
  3. Proposing new topics — open a new issue;
  4. Submitting an improvement — submit a pull request.

When contributing new content, please first discuss the change you wish to make through the corresponding issue before making a change.

Order of priority

Unless agreed otherwise, this is the order of priority by label:

  1. reference, which includes "CI/CD Environment" and "Reference" categories on website.
  2. guided tour
  3. account mgmt
  4. languages
  5. use-case

If you're an external contributor, it's best to start from no.4.

Writing

  • Before submitting a pull request, verify all non-code text with Grammarly (use a free account).
  • Prefer active over passive voice.
  • Always use present tense. There are very few cases in technical writing when you need future or past tense.
  • Edit your first draft to say the same thing with less words. Or in shorter sentences.
  • Verify any configuration or code that's part of your content in a working Semaphore project.

Text formatting

We follow a few rules:

  • All text must be limited to 80 characters, to make discussing changes in pull requests easier.
  • Prefer reference-style links.

When in doubt use any of the current files as an example.

Markdown files need to follow a naming pattern to match records in CMS. If you're an external contributor and would like to create a new page, simply create an .md file with any name and submit a pull request. Someone from the Semaphore team will make sure it's published.