Skip to main content

Contribution guidelines

The Cardano Docs site follows the principles of open-source collaboration, inclusiveness, and community-driven success. Contributing to Cardano Docs helps create a rich, accurate, and up-to-date resource for the entire Cardano community. By sharing your knowledge and expertise, you ensure the documentation remains a valuable and reliable source of information for all.

Note that Cardano Docs focuses on providing information about Cardano's functionalities and features, while the Developer Portal offers developer-related tutorials and guides. These two resources exist in tandem, ensuring a seamless user experience for both general users and developers.

By using this website and contributing to Cardano Docs, you agree to be bound by and comply with the CC BY 4.0 license.

What to contribute?​

You can contribute in several ways, including:

  • Edits: spot typos or inaccuracies? Fix them!
  • Feature overviews: suggest additional overviews or functionality explainers relevant to Cardano
  • References: add more references to community-driven projects or resources
  • Graphics: contribute with graphics, infographics, etc. Please refer to the Cardano branding assets for this.

How to contribute?​

Creating a pull request​

  1. Find the page: navigate to the page you want to edit
  2. Edit the page: click the ‘Edit this page’ button
  3. Make changes: make changes using Markdown (MD) formatting and adhere to the style guidelines (please see below)
  4. Create a pull request: submit your changes through a pull request.

If you prefer working with GitHub locally, follow these steps:

  1. Fork the repository: go to the Cardano Docs GitHub repository and fork it to your account
  2. Clone the repository: clone the forked repository to your local machine
  3. Create a new branch: create a new branch for your changes
  4. Make your edits: edit the documentation files using MD formatting
  5. Commit your changes: commit your changes with a clear and descriptive message
  6. Push to GitHub: push your changes to your forked repository
  7. Submit a pull request: open a pull request from your new branch to the main repository.

See more about Docusaurus set up here.

Raising an issue​

By raising an issue, you can identify areas for improvement, report problems, or suggest new content.

To create an issue:

  1. Go to the GitHub repository: navigate to the Cardano Docs GitHub repository
  2. Create a new issue: click ‘Issues’ and then ‘New issue’
  3. Describe the issue: provide a clear and detailed description of the issue or suggestion
  4. Submit the issue: click ‘Submit new issue.’

Your contributions are vital to maintaining the quality and integrity of Cardano Docs. Whether you’re correcting a typo, adding new content, or suggesting improvements, every contribution helps. Thank you for being an active Cardano community member and helping make Cardano Docs an invaluable resource for everyone.

Style guide​

General notes​

Ensure simplicity, accuracy, and accessibility. Aim for a broad understanding, even for select audiences. Be concise – avoid unnecessary words.

Style principles​

Language

  • Use American English: -ize rather than -ise endings, ‘color’ instead of ‘colour’
  • Avoid slang words
  • Use gender-inclusive pronouns – they/their/them
  • Active voice, avoid passive.

Abbreviations and acronyms

  • No full stops in abbreviations: eg, ie, PhD, etc, v (note, not vs), plc, Inc
  • Write acronyms as said (eg, radar, laser, captcha), use initial caps for entities, avoid capitalization
  • Minimize the use of acronyms and initialisms. Spell out on first use, eg peer-to-peer (P2P)
  • Refer to the Cambridge dictionary.

Legal and investment

  • Avoid investment or legal advice.

Punctuation

  • Use the Oxford/serial comma
  • Use single quote marks: ‘cascading disruption’
  • Use en dash – (option-hyphen on a Mac keyboard; Alt-hyphen on PC)
  • Use a full stop at the end of the last bullet point.

Capitalization

  • Lowercase for job titles, degree names, and university departments
  • Use lowercase after a colon, eg ‘Feature: this feature is about…’
  • Book, film, and game titles should be in italics, and academic papers should be in ‘single quotes’ – avoid subtitles.

Numbers and time

  • Spell out one to nine: one, two, three, four, five, once I caught a fish alive, except for percentages: 1%, 2%, 3%
  • Use numerals for anything higher: 10, 11, 12, 13, 14, 15
  • Spell out million, billion when in prose: there are nine million bicycles in Beijing
  • Use abbreviations for money: £5m, $10bn, 12tn yen
  • When talking generally, use MMMM DD, YYYY format, eg February 1, 2018
  • For technical purposes, use ISO 8601 standard for dates and time: YYYY-MM-DD eg 2018-02-01.

Bullet lists

  • Start with a capital letter and use full stops in complete sentences. You can format the bullet ‘title’ in bold if there is one:
    • Feature name 1. This full sentence describes the feature in more detail.
    • Feature name 2. This full sentence describes the second feature in more detail.
  • Omit full stops in short itemized lists; use it after the last bullet point. For example, the discussed feature includes such items as:
    • Item 1
    • Item 2
    • Item 3.
  • In shorter statements, full stops can also be omitted. For example:
    • Maintain uniformity across all documentation
    • Encourage user interaction with clear instructions
    • Incorporate visuals judiciously to enhance understanding.

Links

  • Write clear and meaningful links; don’t use ‘here’ as a link. Always embed links; don’t just paste one as is.

Headlines and titles

  • Headlines are ‘Sentence case only’. The limited use of capitals is a way of avoiding confusion for proper names. Use initial caps for navigation section names and topic headings.
  • No full stops at the end of headlines, pull quotes, captions, and other display matter, or when referencing figures: just ‘See Figure 1 for details…’.

Markdown features​

Cardano Docs uses Markdown for formatting. Below are the main Markdown features:

Headers

  • Use # for H1, ## for H2, and so on.
# H1

## H2

### H3

Emphasis

  • Use * or _ for italics, ** or __ for bold.
_italic_ or _italic_

**bold** or **bold**

Lists

  • Use - or * for unordered lists and 1. for ordered lists.
- Item 1

- Item 2

* Item 3.

1. First item

2. Second item.

Links

  • Use [text](url) for links.
[Cardano Docs](https://docs.cardano.org/)

Images

  • Use ![alt text](url) for images.

Code

  • Use backticks for inline code and triple backticks for code blocks.

Blockquotes

  • Use > for blockquotes.
> This is a blockquote.

Tables

  • Use | to create tables.
| Header 1 | Header 2 |

|----------|----------|

| Cell 1 | Cell 2 |

For more details, see MD features here.

On this page