zgorizzo69 / curve-docs

Sphinx documentation for curve.readthedocs.io

curve-docs

reStructuredText documentation for curve.readthedocs.io.

Contributing

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.

Writing Style

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.

API Directives

• All API documentation must use standard Python directives.
• Where possible, references to syntax should use appropriate Python roles.
• External references may use intersphinx roles.

Headers

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: #, =, -, *, ^.

License

This project is licensed under the MIT license.