Hedera
  • Welcome to Hedera — let’s build the future
  • Getting Started
    • Environment Setup
    • Web2 Developers
      • Transfer HBAR
      • Create a Token
      • Create a Topic
    • EVM Developers
      • Deploy a Contract
  • Tutorials
    • Smart Contracts
      • How to Mint & Burn an ERC-721 Token Using Hardhat and Ethers (Part 1)
      • How to Set Access Control, a Token URI, Pause, and Transfer an ERC-721 Token Using Hardhat (Part 2)
      • How to Upgrade an ERC-721 Token with OpenZeppelin UUPS Proxies and Hardhat (Part 3)
      • How to Verify a Smart Contract on HashScan
      • Deploy a Smart Contract Using Remix
      • Deploy a Smart Contract Using Hardhat and Hiero JSON-RPC Relay
      • Deploy Your First Smart Contract
      • Deploy a Contract Using the Hedera Token Service
      • Send and Receive HBAR Using Solidity Smart Contracts
      • Deploy By Leveraging Ethereum Developer Tools On Hedera
      • Deploy a Subgraph Using The Graph and Hedera JSON-RPC Relay
      • Deploy Smart Contracts on Hedera Using Truffle
      • The Power of Native Hedera Tokens as ERC-20 Tokens: A step-by-step guide
      • HTS x EVM - Part 1: How to Mint NFTs
      • HTS x EVM - Part 2: KYC & Update
      • HTS x EVM - Part 3: How to Pause, Freeze, Wipe, and Delete NFTs
      • Hedera Smart Contracts Workshop
        • Setup
        • Solidity
        • Hedera SDK JS
        • Hardhat and EthersJs
        • Outro
      • Foundry
        • How to Setup Foundry and Write a Basic Unit Test
        • How to Deploy and Verify a Hedera Smart Contract with Foundry
        • How to Test A Solidity Event
        • How to Fork Testnet on Latest Block
    • Consensus
      • Submit Your First Message
      • Submit Message to Private Topic
      • Query Messages with Mirror Node
    • Tokens
      • Create and Transfer Your First NFT
      • Create and Transfer Your First Fungible Token
      • Create and Transfer an NFT using a Solidity Contract
      • Structure Your Token Metadata Using JSON Schema V2
      • Hedera Token Service - Part 1: How to Mint NFTs
      • Hedera Token Service - Part 2: KYC, Update, and Scheduled Transactions
      • Hedera Token Service - Part 3: How to Pause, Freeze, Wipe, and Delete NFTs
      • Create Your First Frictionless Airdrop Campaign
    • Local Node
      • How to Run Hedera Local Node in a Cloud Development Environment (CDE)
        • Run a Local Node in Gitpod
        • Run a Local Node in Codespaces
      • How to Set Up a Hedera Local Node
      • Set Up a Hedera Local Node using the NPM CLI
    • More Tutorials
      • Create and Fund Your Hedera Testnet Account
      • How to Create a Personal Access Token (API Key) on the Hedera Portal
      • How to Auto-Create Hedera Accounts with HBAR and Token Transfers
      • How to Configure a Mirror Node and Query Data
      • How to Generate a Random Number on Hedera
      • Get Started with the Hedera Consensus Service Fabric Plugin
        • Virtual Environment Setup
      • Schedule Your First Transaction
      • How to Connect to Hedera Networks Over RPC
        • Configuring Hashio RPC endpoints
        • Configuring Hiero JSON-RPC Relay endpoints
        • Configuring Validation Cloud RPC endpoints
      • JavaScript Testing
      • Create a Hedera DApp Integrated with WalletConnect
      • How to Connect MetaMask to Hedera
    • Demo Applications
    • Starter Projects
    • Building on Hedera (course)
  • Networks
    • Mainnet
      • Mainnet Accounts
      • Mainnet Consensus Nodes
        • Node Requirements
          • FAQ
      • Fees
        • Transaction Records
    • Testnets
      • Testnet Accounts
      • Testnet Consensus Nodes
    • Localnet
      • Single Node Configuration
      • Multinode Configuration
    • Network Explorers and Tools
    • Release Notes
      • Consensus Node
      • Hedera Mirror Node
  • Core Concepts
    • Accounts
      • Account Creation
      • Auto Account Creation
      • Account Properties
    • Keys and Signatures
    • Schedule Transaction
    • Smart Contracts
      • Understanding Hedera's EVM Differences and Compatibility
        • For EVM Developers Migrating to Hedera
          • Accounts, Signature Verification & Keys (ECDSA vs. ED25519)
          • JSON-RPC Relay and EVM Tooling
          • Token Management with Hedera Token Service
          • Decimal Handling (8 vs. 18 Decimals)
          • Handling HBAR Transfers in Contracts
        • For Hedera-Native Developers Adding Smart Contract Functionality
          • Integrating ED25519 Accounts and Advanced Features Into Smart Contracts
          • JSON-RPC Relay and State Queries
          • Extending Token Management with Smart Contracts
      • Creating Smart Contracts
      • Compiling Smart Contracts
      • System Smart Contracts
        • Hedera Account Service
        • Hedera Schedule Service
      • Gas and Fees
      • JSON-RPC Relay
      • Deploying Smart Contracts
      • Smart Contract Addresses
      • Verifying Smart Contracts
      • Smart Contract Traceability
      • Tokens Managed by Smart Contracts
        • ERC-20 (Fungible Tokens)
        • ERC-721 (Non-Fungible Token)
        • ERC-3643 Real World Assets (RWA)
        • ERC-1363 (Payable Tokens)
        • Hedera Token Service System Contract
      • Wrapped HBAR (WHBAR)
      • Smart Contract Rent
      • Smart Contract Security
      • EVM Archive Node Queries
    • Tokens
      • Tokenization on Hedera
      • Hedera Token Service (HTS) Native Tokenization
        • Token Types and ID Formats
        • Token Properties
        • Token Creation
        • Custom Fee Schedule
        • Token Airdrops
      • ERC/EVM-Compatible Tokenization
      • Hybrid (HTS + EVM ) Tokenization
    • Staking
      • Staking Program
      • Stake HBAR
    • Hashgraph Consensus Algorithm
      • Gossip About Gossip
      • Virtual Voting
    • Transactions and Queries
      • Transaction Properties
    • State and History
    • Mirror Nodes
      • Hedera Mirror Node
      • One Click Mirror Node Deployment
      • Run Your Own Mirror Node
        • Run Your Own Mirror Node with Google Cloud Storage (GCS)
        • Run Your Mirror Node with Amazon Web Services S3 (AWS)
  • Open Source Solutions and Integrations
    • AI Studio on Hedera
      • ElizaOS Plugin for Hedera
      • Hedera AI Agent Kit
      • MCP Server
      • OpenConvAI
    • AI Tools for Developers
      • Hedera Hivemind
      • Kapa AI
    • Asset Tokenization Studio (ATS)
      • Web User Interface (UI)
      • Frequently Asked Questions (FAQs)
    • HashioDAO
      • Governance Token DAO
      • NFT DAO
      • Multisig DAO
      • DAO Proposals
      • Local Environment Setup
    • Hedera CLI
    • Hedera Contract Builder
    • Hedera Custodians Library
      • How to use it
    • Hedera Developers Code Repository
    • Hedera Developer Playground
    • Hedera Wallet Snap By MetaMask
      • Hedera Wallet Snap Documentation
      • Tutorial: MetaMask Snaps – What Are They and How to Use Them
    • Interoperability and Bridging
      • LayerZero
    • NFT Studio
      • Airdrop List Verifier
      • Metadata Validator
      • NFT Rarity Inspector
      • NFT Token Holders List Builder
      • NFT Risk Calculator
      • Token Balance Snapshot
      • Hedera NFT SDK
    • Oracle Networks
      • Chainlink Oracles
      • Pyth Oracles
      • Supra Oracles
    • Stablecoin Studio
      • Core Concepts
      • Web UI Application
      • CLI Management
      • TypeScript SDK
    • Hedera Guardian
    • Hedera WalletConnect
  • SDKs & APIs
    • SDKs
      • Build Your Hedera Client
      • Set Up Your Local Network
      • Network Address Book
      • Keys
        • Generate a new key pair
        • Import an existing key
        • Create a key list
        • Create a threshold key
        • Generate a mnemonic phrase
        • Recover keys from a mnemonic phrase
      • HBAR
      • Specialized Types
      • Pseudorandom Number Generator
      • Transactions
        • Create a Batch Transaction
        • Transaction ID
        • Modify transaction fields
        • Create an unsigned transaction
        • Manually sign a transaction
        • Submit a transaction
        • Sign a multisignature transaction
        • Get a transaction receipt
        • Get a transaction record
      • Schedule Transaction
        • Schedule ID
        • Create a schedule transaction
        • Sign a scheduled transaction
        • Delete a schedule transaction
        • Get schedule info
        • Network Response Messages
      • Queries
      • General Network Response Messages
      • Accounts and HBAR
        • Create an account
        • Update an account
        • Transfer cryptocurrency
        • Approve an allowance
        • Delete an allowance
        • Delete an account
        • Get account balance
        • Get account info
        • Network Response Messages
      • Consensus Service
        • Create a topic
        • Update a topic
        • Submit a message
        • Delete a topic
        • Get topic messages
        • Get topic info
        • Network Response
      • Token Service
        • Token ID
        • NFT ID
        • Token types
        • Create a token
        • Custom token fees
        • Update a token
        • Update token custom fees
        • Update NFT metadata
        • Transfer tokens
        • Airdrop a token
        • Claim a token
        • Cancel a token
        • Reject a token
        • Delete a token
        • Mint a token
        • Burn a token
        • Freeze an account
        • Unfreeze an account
        • Enable KYC account flag
        • Disable KYC account flag
        • Associate tokens to an account
        • Dissociate tokens from an account
        • Pause a token
        • Unpause a token
        • Wipe a token
        • Atomic swaps
        • Get account token balance
        • Get token info
        • Get NFT info
        • Network Response Messages
      • File Service
        • Create a file
        • Append to a file
        • Update a file
        • Delete a file
        • Get file contents
        • Get file info
        • Network Response Messages
      • Smart Contract Service
        • Delegate Contract ID
        • Create a smart contract
        • Update a smart contract
        • Delete a smart contract
        • Call a smart contract function
        • Ethereum transaction
        • Get a smart contract function
        • Get smart contract bytecode
        • Get smart contract info
        • Hedera Service Solidity Libraries
        • Network Response Messages
      • Signature Provider
        • Provider
        • Signer
        • Wallet
        • Local Provider
    • Mirror Node REST API
      • Accounts
      • Balances
      • Blocks
      • Schedule Transactions
      • Smart Contracts
      • Tokens
      • Topics
      • Transactions
      • Network
    • Hedera Consensus Service gRPC API
    • Hedera APIs
      • Basic Types
        • AccountAmount
        • AccountID
        • ContractID
        • CryptoAllowance
        • CurrentAndNextFeeSchedule
        • FeeComponents
        • FeeData
        • FeeSchedule
        • FileID
        • Fraction
        • HederaFunctionality
        • Key
        • KeyList
        • NftAllowance
        • NftTransfer
        • NodeAddress
        • NodeAddressBook
        • RealmID
        • ScheduleID
        • SemanticVersion
        • ServicesConfigurationList
        • ServiceEndpoint
        • Setting
        • ShardID
        • Signature
        • SignatureList
        • SignatureMap
        • SignaturePair
        • SubType
        • TransferList
        • TransactionID
        • ThresholdKey
        • ThresholdSignature
        • TokenAllowance
        • TokenBalance
        • TokenBalances
        • TokenFreezeStatus
        • TokenPauseStatus
        • TokenID
        • TokenKycStatus
        • TokenRelationship
        • TokenTransferList
        • TokenType
        • TokenSupplyType
        • TopicID
        • TransactionFeeSchedule
      • Cryptocurrency Accounts
        • CryptoService
        • CryptApproveAllowance
        • CryptoDeleteAllowance
        • CryptoCreate
        • CryptoTransfer
        • CryptoUpdate
        • CryptoDelete
        • CryptoGetAccountBalance
        • CryptoGetAccountRecords
        • CryptoGetInfo
        • CryptoGetStakers
      • Consensus Service
        • Consensus Service
        • ConsensusCreateTopic
        • ConsensusUpdateTopic
        • ConsensusSubmitMessage
        • ConsensusDeleteTopic
        • ConsensusTopicInfo
        • ConsensusGetTopicInfo
      • Schedule Service
        • ScheduleService
        • SchedulableTransactionBody
        • ScheduleCreate
        • ScheduleDelete
        • ScheduleSign
        • ScheduleGetInfo
      • Token Service
        • TokenService
        • CustomFees
          • AssessedCustomFee
          • CustomFee
          • FractionalFee
          • FixedFee
          • RoyaltyFee
        • TokenCreate
        • TokenUpdate
        • TokenFeeScheduleUpdate
        • TokenDelete
        • TokenMint
        • TokenBurn
        • TokenFreezeAccount
        • TokenUnfreezeAccount
        • TokenGrantKyc
        • TokenRevokeKyc
        • TokenAssociate
        • TokenDissociate
        • TokenWipeAccount
        • TokenPause
        • TokenUnpause
        • TokenGetInfo
        • TokenGetNftInfo
        • TokenGetNftInfos
        • TokenGetAccountNftInfo
      • File Service
        • FileService
        • FileCreate
        • FileAppend
        • FileUpdate
        • FileDelete
        • FileGetContents
        • FileGetInfo
      • Smart Contracts
        • SmartContractService
        • ContractCall
        • ContractCallLocal
        • ContractCreate
        • ContractUpdate
        • ContractDelete
        • ContractGetByteCode
        • ContractGetInfo
        • ContractGetRecords
      • Miscellaneous
        • Duration
        • ExchangeRate
        • Freeze
        • FreezeType
        • GetByKey
        • GetBySolidityID
        • NetworkGetVersionInfo
        • NetworkService
        • Query
        • QueryHeader
        • Response
        • ResponseCode
        • ResponseHeader
        • SystemDelete
        • SystemUndelete
        • TimeStamp
        • Transaction
        • TransactionBody
        • TransactionContents
        • TransactionGetFastRecord
        • TransactionGetReceipt
        • TransactionGetRecord
        • TransactionReceipt
        • TransactionRecord
        • TransactionResponse
        • UncheckedSubmit
    • Hedera Status API
  • Support & Community
    • Glossary
    • Contributing to Hedera documentation
      • Contribution Guidelines
        • Creating Issues
        • Creating Pull Requests
        • Hedera Improvement Proposal (HIP)
        • Submit Demo Applications
      • Style Guide
        • Understanding different types of documentation
        • Use of HBAR and tinybars
        • Use of web2 and web3
        • Language and grammar
        • Formatting
        • Punctuation
        • GitBook Markdown Syntax
    • Discord
    • GitHub
    • Stack Overflow
    • Hedera Blog
    • Bug Bounty
    • Hedera Help
    • Documentation Survey
    • Meetups
    • Brand Guidelines
    • Status Page
Powered by GitBook
LogoLogo

INTRODUCTION

  • Fees
  • Core Concepts
  • Network Information

TOOLS

  • Bridge
  • Oracles
  • Explorers
  • Developer Portal & Faucet

RESOURCES

  • Status
  • Bug Bounty
  • Build on Hedera (course)
  • Documentation Survey
On this page
  • American English
  • Abbreviations
  • Don't create abbreviations
  • Make abbreviations plural
  • When to spell out a term
  • Active voice
  • Adverbs
  • Articles (a, an, the)
  • Capitalization
  • Contractions
  • Plurals
  • Possessives
  • Prepositions
  • Pronouns
  • Gender-neutral pronouns:
  • Relative pronouns:
  • Second-person pronouns (You, Your)
  • Avoid Future Tense
  • Tone
  • Verb forms
  • The principal or "main" verbs
  • Auxiliary or "helping" verbs
  • "-ing" words (gerunds)

Was this helpful?

Edit on GitHub
  1. Support & Community
  2. Contributing to Hedera documentation
  3. Style Guide

Language and grammar

This page outlines guidelines on language and grammar for Hedera documentation, covering American English spelling, abbreviation usage, active voice, punctuation, and tone.

American English

Follow the American English spelling standard. This means that words should follow the American English conventions, employing 'z' instead of 's' in words such as 'decentralized,' 'realized,' and 'organized.'

For example:

  • Use 'color' instead of the British English 'colour.'

  • Use 'analyze' instead of the British English 'analyse.'

  • Use 'organization' instead of the British English 'organisation.'

Use an American English dictionary or a recognized American English style guide to ensure consistency and accuracy throughout the text. Tools like Grammarly or spell checkers set to American English can assist in maintaining this standard.


Abbreviations

Key Point: Use standard American and industry-standard abbreviations, e.g., NFT for non-fungible tokens. Avoid internet slang.

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 at the end:

    • Dr. for doctor

    • etc. for et cetera

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

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, SDKs, 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 a 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.


Active voice

Always use active voice in procedural documents and use active voice wherever possible in descriptive writing.

  • In active voice, the subject performs the action.

  • In passive voice, The action is performed by the subject.

Examples of the active voice and passive voice

  • ✅ Active voice: Dogs love walks.

  • ❌ Passive voice: Walks are loved by dogs.

  • ❌ Passive voice: Walks are loved.

  • ✅ Active voice: The dog chased the cat.

  • ❌ Passive voice: The cat was chased by the dog.

  • ❌ Passive voice: The cat was chased.

  • ✅ Active voice: [You can] select Save to save the document.

  • ❌ Passive voice: The document can be saved by selecting Save [by you].

When to use the passive voice

There are some rare instances where the passive voice is preferable (for example, when an object is more important than an actor or action). In these cases, the active voice makes for awkward reading.

  • ✅ Acceptable use of the passive voice: The file is saved.

  • ❌ Awkward use of the active voice: You save the file.

  • ❌ Awkward use of the active voice: FUEL saves the file.

Adverbs

Minimize the use of adverbs in your documents because they can affect clarity.

Try to find an alternative phrasing that does not use an adverb.

  • ❌ Not recommended: Browse to the Updates menu manually.

  • ✅ Recommended: Go to Updates.

  • ❌ Not recommended: Immediately reboot the system.

  • ✅ Recommended: When the process has finished, restart the system.

Articles (a, an, the)

For ease of reading, use "a", "an", and "the" in your writing.

"A" and "an" are indefinite articles and are used before a singular noun. They refer to any member of a group.

"The" is a definite article. It is used before singular and plural nouns and refers to one or more particular members of a group. Whether you use "a" or "an" depends on the pronunciation of the word that follows. Use "a" before any consonant sound; use "an" before any vowel sound.

Examples

  • An hour

  • An HTML entity

  • A hand

  • A hotel

  • An umbrella

  • A union


Capitalization

Key Point: Use standard American capitalization. Use sentence case for headings.

  • 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 Mirrornet.

  • Do not use all-uppercase or camelcase 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.


You should structure sentences to have the main clause before any subordinate clauses.

However, there are times when you might want to start a sentence with a subordinate clause. If you are combining instructional and conceptual writing in a sentence, or if a particular circumstance predetermines an action, you might want to start a sentence with a subordinate clause. When doing this, separate the subordinate clause from the main clause with a comma.

When to have the main clause first

  • ✅ Recommended: You can work in three areas to achieve this...

  • ❌ Not recommended: To achieve this, you can work in three areas...

  • ✅ Recommended: We must address several questions before we can develop the new system.

  • ❌ Not recommended: Before we can develop the new system, we must address several questions.

When to have the subordinate clause first

  • ❌Not recommended: Read Document x for more information.

  • ✅ Recommended: For more information, read Document x.


Contractions

Do not use contractions ("isn't" for "is not", "won't" for "will not") in technical documentation.

Its and it's

Do not confuse "its" (possessive) with "it's" (contraction of "it is").

  • ❌ Not recommended: Its going to take three nodes.

  • ✅ Recommended: It's going to take three nodes.

  • ❌Not recommended: By default, the CLI tool hides the majority of it's flags.

  • ✅ Recommended: By default, the CLI tool hides the majority of its flags.


Plurals

Use either the singular or plural construction most relevant to your topic and keep it consistent in your document. Single constructions may be more relevant to some articles than plural constructions, and vice versa.

Use optional plurals in parentheses as a last resort.

  • ✅ Recommended: Developers will be able to navigate through this area.

  • ✅ Recommended: The Developer will be able to navigate through this area.

  • ❌ Not recommended: Developer(s) will be able to navigate through this area.


Possessives

In general, form singular possessives by adding an apostrophe-s.

For words ending in "s" and plurals, add an apostrophe without the additional "s".

Sometimes, it may be clearer to use "[object] of [noun ending in "s"]" rather than "[noun ending in "s"]' [object]".

NOTE: The possessive of "it" ("its") is a special case because it doesn't take an apostrophe.

Examples

  • ...the node's properties (singular)

  • ...the nodes' properties (plural)


Prepositions

Use prepositions as needed, even at the end of sentences. It's OK to end a sentence with a preposition when it improves readability.

  • ✅ Recommended: Open the software this document refers to.

  • ❌ Not recommended: Open the software to which this document refers.


Pronouns

Be considerate in the use of pronouns. Ensure that pronouns refer to their antecedents (the nouns they are replacing).

Gender-neutral pronouns:

Do not use gender-specific pronouns unless the person you are referring to identifies as that gender.

When referring to the users, use "they/them/their".

Do not use "he/she" or "(s)he".

Relative pronouns:

The three main relative pronouns are "that", "which", and "who".

Do not confuse "that" with "which". "That" is used to introduce a restrictive relative clause; "which" is used to introduce a non-restrictive relative clause. If you cannot remove a relative clause without affecting the meaning of the sentence, use "that" without a comma. If the relative clause can be removed without affecting the meaning, use "which" with a comma.

  • ✅ Recommended use of "that": Hedera creates products that are exclusive to web3.

  • ❌ Not recommended use of "that": Hedera creates products that are exclusive to web3.

  • ✅ Recommended use of "which": Hedera's dashboard is customisable, which allows users to customize it as per their needs.

  • ❌ Recommended (not using "which"): Hedera's dashboard is customisable for the users.

When referring to a person, use "who" rather than "that".

  • ✅ Recommended: The user who saved the file.

  • ❌ Not recommended: The user that saved the file.

However, you can use "whose" to refer to people and things. "Whose" is the possessive form of both "who" and "which".

Second-person pronouns (You, Your)

Use the second person "you" in the documentation. Try to limit your use of the first person ("I"/"we").

The implicit "you"

Sometimes, you don't need to write "you".

  • ✅ Recommended: When deleting files...

  • ❌ Not recommended: If you are deleting files...

  • ❌ Not recommended: If we're deleting files...

When using the implicit "you", be clear about who is performing the action.

Imperatives

When writing an instruction, leave out the "you".

  • ✅ Recommended: Select OK.

  • ❌ Not recommended: Let's select OK now.

  • ❌ Not recommended: You can now select OK.

This issue can also interact with tense.

  • ❌ Not recommended: You'll need to create a spreadsheet.

  • ✅ Recommended: Create a spreadsheet.

Using "we"

It's OK to use "we" to avoid the passive voice. However, try and find a simpler alternative if possible.

  • ❌Not recommended: It is recommended that you do not delete these files.

  • ✅ Recommended (OK): We recommend that you do not delete these files.

  • ✅ Recommended (Better): Do not delete these files.

"Users" versus "you"

Do not use "users" (or derivatives like "engineers" or "developers") instead of "you". Think about who will be reading your document and direct content that is relevant to their job.

  • ✅ Recommended: You can do x...

  • ❌ Not recommended: Developers can do x...

Sometimes, you might have to talk to your reader about other team members. Try to be specific, use correct job titles, and capitalize accordingly.

  • ❌ Not recommended: If you need access to a specific application, talk to someone in the Engineering team.

  • ✅ Recommended: Engineers can provide you access to a specific application.


Avoid Future Tense

Write technical documentation in the present tense rather than the future tense. Future tense is used only when necessary.

Avoid using "will":

  • ❌ Not recommended: Selecting OK will save your file to the shared drive.

  • ✅ Recommended: Select OK to save your file to the shared drive.

Also, try to avoid the hypothetical future "would":

  • ❌ Not recommended: The textures would be loaded into the editor.

  • ✅ Recommended: The textures are loaded into the editor.


Tone

The content is concise and direct with an appropriate tone. Avoid slang or non-English words.

Avoid the following content

  • Buzzwords or unqualified technical jargon.

  • Figures of speech.

  • Placeholder phrases like "please note" or "at this time".

  • Long-winded sentences.

  • Starting all sentences with the same phrase, like "you can" or "to do".

  • Pop-culture references.

  • Jokes.

  • Swearing.

  • Exclamation marks.

  • Metaphors and similes.

  • Phrases that insult any group of people.

  • Phrasing in terms of "let's" do something.

  • Using phrases like "simply" or "easily" in a procedure. What you find easy, others may not.

  • Internet slang or abbreviations like "ymmv" and "tl;dr".

Use of "please"

Using "please" in a set of instructions isn't necessary.

  • ❌ Not recommended: Please select Save.

  • ✅ Recommended: Select Save.


Verb forms

Use the appropriate verb forms for technical documentation. Prioritize principal or "main" verbs in procedural writing. Auxiliary or "helping" verbs may be used in descriptive writing if there is no better alternative.

The principal or "main" verbs

A principal verb is the most important verb in a sentence. It shows the action, state, or being of the subject. Principal verbs can stand alone. Use the transitive form in procedural writing. Transitive verbs take a direct object while intransitive verbs do not. Intransitive verbs are ambiguous, so avoid them if possible.

  • ❌ Example of an intransitive principal verb: The user started.

  • ✅ Example of a transitive principal verb: The user started the Grafana dashboard.

Auxiliary or "helping" verbs

Auxiliary verbs support the main verb as part of a verb phrase. Auxiliary verbs cannot stand alone. They need to be paired with main verbs to communicate action, changing tense and meaning in the process. This can create ambiguity and lead to "-ing" words, so avoid them in procedural writing.

  • ❌ Example of an auxiliary verb: I was playing the game.

  • ❌ Example of an auxiliary verb: I had played the game.

  • ❌ Example without an auxiliary verb: I played the game.

"-ing" words (gerunds)

Avoid using verb forms ending in "-ing" in procedural writing.

  • ❌ Not recommended: If you are creating a track,...

  • ✅ Recommended: To create a track,...

  • ❌ Not recommended: Selecting OK saves the file.

  • ✅ Recommended: Select OK to save the file.

PreviousUse of web2 and web3NextFormatting

Last updated 6 months ago

Was this helpful?

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

If you're unsure whether a word is an abbreviation or a shortened version of a word, look in this list of . 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.

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

whether to use a or an.
resources
capitalization