reStructuredText documentation for curve.readthedocs.io.
Contributions to documentation are always welcome! Feel free to open a pull request of any size.
We adhere to the following guidelines within our documentation. Reviewing them will help ensure a quick and painless code review if you are making a significant contribution.
We use imperative, present tense to describe APIs: “return” not “returns”. One way to test if we have it right is to complete the following sentence:
“If we call this API it will: ...”
For narrative style documentation, we prefer the use of first-person “we” form over second-person “you” form.
Additionally, we recommend the following best practices when writing documentation:
- Use terms consistently.
- Avoid ambiguous pronouns.
- Eliminate unneeded words.
- Establish key points at the start of a document.
- Focus each paragraph on a single topic.
- Focus each sentence on a single idea.
- Use a numbered list when order is important and a bulleted list when order is irrelevant.
- Introduce lists and tables appropriately.
Google’s technical writing courses are a valuable resource. We recommend reviewing them before any significant documentation work.
- All API documentation must use standard Python directives.
- Where possible, references to syntax should use appropriate Python roles.
- External references may use intersphinx roles.
Each documentation section must begin with a label of the same name as the filename for that section. For example, if the filename for a section is style-guide.rst, the RST opens with a label _style-guide.
Section headers should use the following sequence, from top to bottom: #, =, -, *, ^.
This project is licensed under the MIT license.