Midnight documentation style guide
This comprehensive style guide establishes writing and formatting standards for all Midnight technical documentation. It ensures consistency, clarity, and accessibility across our documentation ecosystem.
Based on industry standards
This guide builds upon the Microsoft Writing Style Guide and Google Developer Documentation Style Guide. For general formatting and style questions not covered here, refer to these industry-standard resources. This guide focuses on Midnight-specific conventions and blockchain terminology.
Core writing principles
Active voice and direct language
Use active voice consistently to create clear, actionable content.
| ✓ Preferred | ✗ Avoid |
|---|---|
| Install the Lace wallet extension | The Lace wallet extension should be installed |
| The proof server generates zero-knowledge proofs | Zero-knowledge proofs are generated by the proof server |
| Deploy your smart contract to testnet | Your smart contract should be deployed to testnet |
Present tense and immediate instructions
Write instructions in present tense as if the user is performing actions now.
| ✓ Preferred | ✗ Avoid |
|---|---|
| Click the send button. | You will click the send button. |
| The transaction completes successfully. | The transaction will complete successfully. |
| Your wallet displays the balance. | Your wallet will display the balance. |
Sentence case convention
Use sentence case for all headings, titles, and labels to maintain consistency and accessibility.
| ✓ Preferred | ✗ Avoid |
|---|---|
| Getting started with Midnight | Getting Started With Midnight |
| Building your first DApp | Building Your First DApp |
| API reference guide | API Reference Guide |
User-centered language
Write from the user's perspective using "you" instead of "we" or "one."
| ✓ Preferred | ✗ Avoid |
|---|---|
| You can send transactions using the Lace wallet. | One can send transactions using the Lace wallet. |
| Configure your development environment. | We recommend configuring your development environment. |
| Your proof server handles ZK computation. | Users should configure their development environment. |
Midnight-specific terminology
Capitalization standards
Always capitalize the following terms:
- Midnight (the blockchain network)
- Testnet (when referring to the test network)
- Mainnet (when referring to the production network)
- Lace (the wallet name)
- DApp (decentralized application)
- ZK (zero-knowledge, when used as abbreviation)
Use lowercase for the following terms:
- tDUST (testnet tokens - lowercase 't', uppercase 'DUST')
- proof server (unless beginning a sentence)
- smart contract (unless beginning a sentence)
- zero-knowledge (when spelled out, unless beginning a sentence)
Technical terms
Midnight-specific terms:
- tDUST tokens: Test tokens on Midnight testnet
- proof server: Infrastructure for generating zero-knowledge proofs
- privacy-preserving: Preferred over "private" when describing transactions
- ZK proofs: Acceptable abbreviation for zero-knowledge proofs
Consistent terminology:
- Use "wallet address" not "wallet ID"
- Use "transaction hash" not "transaction ID"
- Use "smart contract" not "contract" (unless context is clear)
- Use "DApp" not "dApp" or "dapp"
Content structure standards
Page organization
- Clear title in sentence case
- Brief introduction explaining the page's purpose
- Target audience (when relevant)
- Prerequisites (when applicable)
- Step-by-step instructions (for procedures)
- Next steps or related content
- Troubleshooting (when relevant)
Heading hierarchy
Use consistent heading structure:
# Page title (H1) - only one per page
## Major sections (H2)
### Subsections (H3)
#### Details (H4) - use sparingly
Heading guidelines:
- Use sentence case
- Be descriptive and scannable
- Include keywords naturally
- Avoid gerunds when possible ("Install tools" vs "Installing tools")
Prerequisites formatting
Use collapsible details for comprehensive prerequisites:
<details>
<summary><strong>System requirements</strong></summary>
**Minimum requirements:**
- RAM: 8GB
- Storage: 10GB free space
- OS: macOS, Linux, or WSL2
</details>
Procedural documentation
Action starting with verb Step-by-step instructions
Use the <Step> and <Flow> components for procedures:
### Install Lace wallet
Install the Lace wallet extension for Midnight transactions.
(The steps render incrementally)
<Flow>
<Step>
Search for "Lace wallet"
</Step>
<Step>
Click "Add to Chrome"
<Step>
**Verification**: The Lace icon appears in your toolbar.
</Step>
</Flow>
Action verbs
Use specific, action-oriented verbs:
| ✓ Preferred verbs | ✗ Avoid vague verbs |
|---|---|
| Click, select, choose | Do, make, get |
| Navigate, go to, visit | Use, utilize, leverage |
| Enter, type, paste | Perform, execute, implement |
| Install, download, configure | |
| Deploy, publish, submit |
Error handling
Include common errors and solutions:
:::caution[Common error]
If you see "Connection refused" error, ensure your proof server is running on port 6300.
**Solution**: Restart the proof server with the correct port configuration.
:::
Code documentation standards
Code blocks
Use proper syntax highlighting and include context:
**Install dependencies:**
```bash
npm install @midnight/sdk
Configure your environment:
const config = {
network: 'testnet',
proofServer: 'http://localhost:6300'
};
### API documentation
Follow consistent API documentation format:
```markdown
### `sendTransaction()`
Sends a transaction to the Midnight network.
**Parameters:**
- `to` (string): Recipient wallet address
- `amount` (number): Amount in tDUST
- `options` (object, optional): Transaction options
**Returns:** Promise\<TransactionHash\>
**Example:**
```javascript
const hash = await sendTransaction(
'mn_shield-addr_test1...',
10.0,
{ privacy: true }
);
### Variable naming
Use consistent naming in examples:
| ✓ Preferred | Context |
|--------------------|-----------------------------------------|
| `walletAddress` | camelCase for JavaScript |
| `transaction_hash` | snake_case for APIs |
| `PROOF_SERVER_URL` | CONSTANT_CASE for environment variables |
## Visual elements
### Admonitions
Use appropriate admonition types:
```markdown
:::tip[Helpful hint]
Use this for optimization tips and best practices.
:::
:::info[Additional information ]
Use this for supplementary context and explanations.
:::
:::warning[Important notice]
Use this for critical information users must know.
:::
:::caution[Potential issues]
Use this for common pitfalls and error prevention.
:::
:::danger[Critical warning]
Use this sparingly for serious security or data loss risks.
:::
Tabs for multiple options
Use tabs for alternative approaches:
<Tabs>
<TabItem value="mac" label="macOS">
Instructions for macOS users.
</TabItem>
<TabItem value="linux" label="Linux">
Instructions for Linux users.
</TabItem>
</Tabs>
Images and diagrams
Image guidelines:
- Use descriptive alt text
- Include captions when helpful
- Optimize for different screen sizes
- Use consistent styling
*Figure 1: Lace wallet displaying tDUST balance*
Metadata standards
Page frontmatter
Use consistent metadata structure:
---
title: Page title in sentence case
description: SEO-friendly description, 120-160 characters
sidebar_position: 1
sidebar_label: Short navigation label
tags: [category, topic, lowercase]
slug: /custom-url-path
---
SEO optimization
Description guidelines:
- 120-160 characters for optimal SEO
- Include primary keywords naturally
- Write compelling copy that encourages clicks
- Use sentence case
Keywords:
- 5-10 relevant terms
- All lowercase
- Include variations and synonyms
- Focus on user intent
Accessibility standards
Inclusive language
| ✓ Use inclusive terms | ✗ Avoid |
|---|---|
| Allowlist | Whitelist |
| Blocklist | Blacklist |
| Primary/secondary | Master/slave |
| Users | Guys |
Screen reader compatibility
Guidelines:
- Use proper heading hierarchy
- Include alt text for images
- Use descriptive link text
- Structure content logically
| ✓ Preferred link text | ✗ Avoid |
|---|---|
| Download the Midnight SDK | Click here |
| View the complete API reference | Read more |
| This link |
Review and quality standards
Content review checklist and common issues
Before publishing, verify the following:
Writing quality:
- Active voice used throughout
- Present tense for instructions
- Sentence case for headings
- Clear, specific language
- No unnecessary jargon
Technical accuracy:
- All code examples tested
- Links work correctly
- Screenshots are current
- Instructions are complete
- Prerequisites are accurate
Formatting:
- Proper heading hierarchy
- Consistent terminology
- Appropriate admonitions
- Complete metadata
- Mobile-friendly layout
Avoid these common issues
Writing issues:
- Passive voice construction
- Future tense in instructions
- Inconsistent terminology
- Overly complex sentences
- Missing context for steps
Technical issues:
- Outdated code examples
- Broken internal links
- Missing error handling
- Incomplete procedures
- Unclear prerequisites
Formatting issues:
- Inconsistent heading case
- Wrong admonition types
- Missing alt text
- Improper code highlighting
- Cluttered page structure
Tools and resources
Recommended tools
Writing:
- Grammarly - Grammar and style checking
- Hemingway Editor - Readability analysis
Documentation:
- Docusaurus - Documentation platform
- Markdown Guide - Markdown reference
- PlantUML - Diagram generation
Reference materials
Industry style guides:
Blockchain-specific resources: