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
  • Introduction
  • Types of Documentation
  • Instructional documentation
  • Components of instructional documents
  • Conceptual documentation
  • Components of conceptual documents
  • Reference documentation
  • Components of reference documents

Was this helpful?

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

Understanding different types of documentation

This page provides an overview of the three primary types of documentation — Instructional, Conceptual, and Reference — highlighting their distinct purposes, structures, and writing styles.

Introduction

To create effective and useful documentation, it is important to recognize the different types of documentation as not all documentation serves the same purpose or audience. We can divide documentation into three broad categories: instructional, conceptual, and reference. Each documentation type fulfills a different purpose and has different style and structural requirements.

This page will help you understand these three types of documentation.


Types of Documentation

The three different types of documentation can be defined as follows:

  • Instructional documentation provides the reader with a clear and direct step-by-step process they can follow to complete a defined task.

  • Conceptual documentation helps the reader to understand a broad idea about a feature or product.

  • Reference documentation gives the reader comprehensive information about a part of a system.

Sometimes, a topic might require more than one type of document.

For example, instructional documents can reinforce ideas in conceptual documents by giving practical examples of use cases or prescribed processes that adhere to a defined artistic style.

Similarly, use a reference document to define all supplementary information to avoid overloading your conceptual document, which is free to focus on explaining the high-level themes of the area.

Conceptual and reference documents are similar in structure but differ significantly in depth and style. Conceptual documents aim for a high-level summary and brush over the fine details. Reference documents instead hone in on the minutiae. Reference documents also require more control over how they are written to ensure clarity in communication. Conceptual documents can be a bit looser.


Instructional documentation

Instructional documents are your "how-to" guides. An instructional document should focus on a single clearly defined task and give readers simple instructions on how to achieve said task.

Components of instructional documents

Page title

Instructional documents use the gerund ("-ing" word) phrasing in their page titles. Titles include a brief description of the task and the tool that will be used. This gives readers a clear idea about what the page is (and is not).

Do not use "how to" phrasing in titles because this will create visual noise if all document names begin with "how to".

  • ❌ Not recommended: Build Manager

  • ❌ Not recommended: Sync a build

  • ❌ Not recommended: How to sync a build

  • ✅ Recommended: Syncing a build with the Build Manager

Introduction

Every instructional document must have a concise introduction that explains what the topic and task are in basic terms. It's a good idea to include a high density of keywords in the introduction to maximize search engine optimization.

Elements of Instructional introductions

Element
Description
Mandatory

Context

Gives the reader background information so they can understand not only what they are working with, but why they are working with it.

✅

Content

Tells the reader exactly what the page covers. This eliminates ambiguity about the instructions the reader can expect to find.

✅

Prerequisites

If the reader needs to have done something before attempting this task, it must be explained here. Link to relevant documents where possible.

❌

Caveats

If there are important issues the reader needs to be made aware of (for example, a tool has a known bug), alert them here.

❌

Procedure

This section is required. An instructional document consists of one or more steps required to complete the procedure. The content of the instructional document must be broken down into small, meaningful units that are ordered sequentially. Each step describes one action. Support the action with focused screenshots or code snippets where possible.

For multiple-step procedures, use the numbered list.

For single-step procedures, use an unnumbered bullet instead of a numbered list.

The instructions or steps are phrased in the imperative form (i.e., "do" rather than "doing").

For example:

  • ❌ Not recommended: 1. Opening the Build Manager

  • ✅ Recommended: 1. Open the Build Manager

To be effective, instructional documentation must consist mainly of procedural writing. This means short sentences of no more than 20 words, use of imperatives, and consistency in the active voice.

Additional resources

This is an optional section. Use this area to link to other material related to the contents of the current document. These could be other instructional documents or conceptual and reference documents.


Conceptual documentation

Conceptual documents describe ideas and theories. They help readers build a foundational understanding of a topic. Ensure that your conceptual documents are brief and to the point so that your reader does not get lost or overwhelmed.

Components of conceptual documents

Introduction

The key points of a conceptual document must be summarized at the top of the page. This lets readers quickly determine what the document covers and whether it is relevant to what they want to learn.

Elements of Conceptual introductions

Element
Description
Mandatory

Context

Gives the reader background information about the concept so they can understand not only what they are reading about, but why it is important.

✅

Content

Tells the reader exactly what the page covers. This eliminates ambiguity about the information the reader can expect to find.

✅

Related

concepts

If there are related documents the reader should also read in order to have a full understanding of a concept, link them here.

❌

Key topics

The concept body describes the subject of the concept. Conceptual content should be organized into logical units. Conceptual documents should use graphics, images, and diagrams to reinforce their ideas. Avoid including instructions for actions. However, in some cases, a concept or reference module can include suggested actions if those actions are simple, highly context-dependent, and don't belong in any procedure module. In such cases, ensure the heading of the concept or reference remains a noun phrase, not a gerund.

When writing a conceptual document, ask yourself the following questions:

  • Is the idea communicated completely?

  • Is there any information that detracts from the central concept?

  • Is there too much granular detail about background information or technical processes?

  • If I was a reader who knew nothing about this topic, is there anything else I would need (or like) to know?

Additional resources

This is an optional section. It is a good idea to use your conceptual document as a hub that links to relevant instructional and reference documents.


Reference documentation

Reference documents exist to deliver condensed technical information about a particular system. An example of a reference document would be a list of all parameters in a given API that indicates which parameters are mandatory or optional, with code snippets of sample API calls. Reference documents can also be used to describe all functions in a particular UI, particularly when interactions don't justify their instructional documents. Reference documents are effectively a compilation of mini-instructional documents.

Reference documents of a given type (such as API references) should be stylistically identical. The standardized presentation builds trust in the reader and allows them to gain an understanding of where particular information is likely to be found.

Components of reference documents

Introduction

Use the introduction to explain what you are providing a reference for. This allows readers to check if they are in the right place. A short description makes the module more usable because users can quickly determine whether the reference is useful without having to read the entire module. It might also be useful to explain what is NOT included for the sake of clarity.

Elements of Reference introductions

Element
Description
Mandatory

Context

Gives the reader background information about what is being referenced.

✅

Content

Tells the reader exactly what the page covers. This eliminates ambiguity about the information the reader can expect to find.

✅

Exclusions

If your reference document does not include something that readers might expect, or if there is common confusion about what is included in the area you are covering, explain what is not included here.

Provide links to relevant documents if available.

❌

Reference areas

Reference content must be segmented into logical areas. Due to the density of information on reference pages, it is easy for readers to become overwhelmed. To prevent this, use the most basic language and simple phrasing as possible.

Any examples contained in a reference document must be generic. Specific examples should be delivered in an instructional document.

When writing a reference document, ask yourself the following questions:

  • Is the area fully referenced?

  • Is there any information that detracts from the document?

  • Are there any important caveats?

  • Is there anything the reader should NOT do?

  • If I was a reader who knew nothing about this topic, is there anything else I would need (or like) to know?

Additional resources

This is an optional section. If you are covering one area of a larger tool or system in this reference document, ensure that there is an easy route to reference documents and instructional documents related to the other areas.

PreviousStyle GuideNextUse of HBAR and tinybars

Last updated 6 months ago

Was this helpful?