CONTRIBUTING.md

Contribution guide

Table of contents

1. Coding style guide
2. Documentation style guide

Coding style guide

Source code comments

Follow the NatSpec format for documentating smart contract source code. Please adhere to a few additional standards:

• Choose /** */ over /// for multi-line NatSpec comments, to save column space
• Omit the usage of @notice, this will be automatically picked up so it will save column space and improve readability
• Take advantage of inheritance for docs (such as documenting the interface), if you need to specify inherited docs use @inheritdoc

Git standards

Commits

Try to specify the scope of your change via a conventional commit (eg. enhance(docs): improve some section) or specifying the scope in brackets (eg. [docs] improve some section).

Documentation style guide

Document types

Group documentation under one of the four categories:

• Tutorials
• Guides
• Concepts
• Reference

Philosophy

• Aim for "better" instead of "perfect" -- any enhancement is a worthwhile improvement.
• Create the minimum viable documentation.
• Don't repeat yourself, use links to existing documentation or inherit it.
• Generate documentation automatically from source code whenever possible.
• Keep your comments as close as possible to the actual source code it is describing.

Standards

Tone and content

• Use descriptive link text.
• Write accessibly.
• Write for a global audience.

Language and grammar

• Use second person: "you" rather than "we".
• Use active voice: make clear who's performing the action.
• Put conditional clauses before instructions, not after.

Formatting, punctuation, and organization

• Use sentence case for document titles and section headings.
• Use numbered lists for sequences.
• Use bulleted lists for most other lists.
• Use description lists for pairs of related pieces of data.
• Use serial commas.
• Use unambiguous date formatting.

Images

• Use SVG files or crushed PNG images.
• Provide alt text.

Code blocks

• Do not use $ in shell blocks.

  Incorrect ❌:

  $ echo "this is worse for copy paste"

  Correct ✅:

  echo "this is better for copy paste"

• Escape new lines.

  Incorrect ❌:

  echo "going to pretend that this"
  && echo "is some really long command"

  Correct ✅:

  echo "at least the command" \
  && echo "looks good when copy pastad"

References

• Diátaxis
• Google dev docs highlights
• Google docs styleguide