Skip to content

Latest commit

 

History

History
95 lines (61 loc) · 6.39 KB

contributing-guide.md

File metadata and controls

95 lines (61 loc) · 6.39 KB
description
Welcome to Hedera docs contributing guide! Ways you can contribute below⬇:

Contributing Guide

Create new issues and pull requests

If you find something that needs to be updated or would like to publish additional content to the docs site you may do so by the following methods:

  • Log an issue
    • You may submit an issue directly on the hedera-docs repository
  • Create a pull request
    • Fork the repository and submit a pull request that includes the suggested updates

{% hint style="info" %} Key Point: Issues and pull requests will be reviewed by the Hedera team. {% endhint %}

Hedera Improvement Proposal (HIP)

Have a new feature request for consensus or mirror nodes? Looking to submit a standard or informational guide for the Hedera ecosystem? Submit a Hedera Improvement Proposal that will be reviewed and evaluated by the Hedera Team. These improvement proposals can range from core protocol changes to the applications, frameworks, and protocols built on top of the Hedera public network and used by the community. To view all active and pending HIPs, check out the HIP website.

  1. Fork the hedera-improvement-proposal repository here.
  2. Fill out this HIP template.
  3. Create a pull request against hashgraph/hedera-improvement-proposal main branch.

Note: Which category should you make the HIP? See hip-1 for details on the HIP process or watch the following video tutorial.

{% embed url="https://www.youtube.com/watch?v=Gbk8EbtibA0" %}

Style Guide

Capitalization

{% hint style="info" %} Key Point: Use standard American capitalization. Use sentence case for headings. {% endhint %}

Follow the standard capitalization rules for American English. Additionally, use the following style standards consistently throughout the Hedera developer documentation:

  • Follow the official capitalization of Hedera products, services, or terms defined by open-source communities, e.g., Hedera Consensus Service, Hedera Improvement Proposal, and Secure Hashing Algorithm.
  • Capitalize each instance of network names mainnet, testnet, and mirrornet only when preceded by Hedera, e.g., Hedera Mainnet, Hedera Testnet, and Hedera Mirrrornet.
  • Do not use all-uppercase or camel case except in the following contexts: in official names, abbreviations, or variable names in a code block, e.g., HBAR, HIPs, or SHA384.
  • You should revise any sentence starting with lowercase word stylization to avoid creating a sentence with a lowercase word.

Abbreviations

{% hint style="info" %} Key Point: Use standard American and industry-standard abbreviations, e.g., NFT for non-fungible token. Avoid internet slang. {% endhint %}

Abbreviations include acronyms, initialisms, shortened words, and contractions. In most contexts, the technical distinction between acronyms and initialisms isn't relevant; it's OK to use the phrase acronym to refer to both.

  • An acronym is formed from the first letters of words in a phrase/name but pronounced as if it were a word itself:
    • WAGMI for We're All Gonna Make It
    • DAO for Decentralized Autonomous Organization
  • An initialism is from the first letters of words in a phrase, but each letter is individually pronounced:
    • KYC for Know Your Customer
    • IPFS for InterPlanetary File System
  • A shortened word is just part of a word or phrase, sometimes with a period in the end:
    • Dr. for **** doctor
    • etc. for et cetera

Note: Some abbreviations can be either acronyms or initialisms, depending on the speaker's preference—examples include FAQ and SQL. In some cases, the pronunciation determines whether to use a or an.

Long and short versions of a word

The short versions of the words are not abbreviations; if you use them, you don't need to put a period after them—for example:

  • application and app
  • synchronize and sync

If you're unsure whether a word is an abbreviation or a shortened version of a word, look in this list of resources. If that doesn't settle the issue, use the speaking test: if you speak the short version as a word (This is a demo version of the product), you can usually treat it as a word and not an abbreviation.

Don't create abbreviations

Use recognizable and industry-standard acronyms and initialisms. Abbreviations are intended to save the writer and the reader time. If the reader has to think twice about an abbreviation, it can slow down their reading comprehension.

Make abbreviations plural

Treat acronyms, initialisms, and other abbreviations as regular words when making them plural—for example, APIs, SKEs, and IDEs.

When to spell out a term

In general, when an abbreviation is likely to be unfamiliar to the audience, spell out the first mention of the term and immediately follow with the abbreviation in parentheses, for example:

  • Miner Extracted Value (MEV)
  • elliptic-curve cryptography (ECC)

For all subsequent mentions of the term, use the abbreviation by itself. If the first mention of a term occurs in a heading or title, you can use the abbreviation and then spell out the abbreviation in the first paragraph that follows the heading or section title.

In some cases, spelling out an acronym doesn't help the reader understand the term. For example, writing out portable document format doesn't help the reader understand what a PDF document is.

Note: The following acronyms rarely need to be spelled out: API, SDK, HTML, REST, URL, USB, and file formats such as PDF or XML.