Technical Writing Cheatsheets: Essential Quick References for Every Documentation Task

Having the right reference material at your fingertips can dramatically improve both the speed and quality of your technical writing. This comprehensive collection of cheatsheets covers everything from grammar and style conventions to documentation structure patterns and formatting standards. Bookmark this page and use it as your go-to reference whenever you're writing or reviewing technical documentation.

Grammar and Style Quick Reference

Active vs. Passive Voice

Technical writing strongly favors active voice because it is clearer, more direct, and easier to understand. Active voice identifies who performs the action, reducing ambiguity. Use passive voice only when the actor is unknown, irrelevant, or when you deliberately want to emphasize the action over the actor.

Active (preferred): The system validates the input before processing the request. The user clicks the Submit button to save changes. The API returns a JSON response containing the requested data.

Passive (avoid when possible): The input is validated before the request is processed. The Submit button is clicked to save changes. A JSON response is returned containing the requested data.

Acceptable passive: The configuration file is generated automatically during installation. (The actor — the installer — is implied and less important than the action.)

Tense Guidelines

Use present tense for descriptions of current functionality and general truths. Use imperative mood for instructions and procedures. Avoid future tense in most documentation — say what the system does, not what it will do.

Present tense: The dashboard displays real-time metrics. The API accepts both JSON and XML formats. Configuration changes take effect immediately.

Imperative mood (for instructions): Click Settings to open the configuration panel. Enter your API key in the authentication field. Save the file and restart the service.

Avoid: The system will display an error message. (Use: The system displays an error message.) Clicking the button will save your changes. (Use: Click the button to save your changes.)

Commonly Confused Terms in Tech

Login vs. Log in: "Login" is a noun or adjective (the login page, your login credentials). "Log in" is a verb (log in to your account). Never use "login" as a verb.

Setup vs. Set up: "Setup" is a noun or adjective (the setup wizard, complete the setup). "Set up" is a verb (set up your development environment).

Backup vs. Back up: "Backup" is a noun or adjective (create a backup, the backup file). "Back up" is a verb (back up your database regularly).

Email vs. E-mail: Modern style guides prefer "email" without the hyphen. Apply the same pattern to "ecommerce" and similar terms.

Web page vs. Webpage: Both are acceptable, but be consistent throughout your documentation. Most modern style guides accept the single word "webpage."

Document Structure Patterns

How-To Guide Template

Follow this structure for task-oriented documentation that guides users through a specific procedure:

Title: Start with a verb phrase — "Configure SSO Authentication" not "SSO Authentication Configuration."

Introduction (2-3 sentences): State what the user will accomplish and why it matters. Mention any important context or time estimates.

Prerequisites: List everything the user needs before starting — required permissions, installed software, configuration values, and prior completed steps.

Steps: Number each step. Start each step with an imperative verb. Include one action per step. Show expected results after critical steps. Include screenshots for complex UI interactions.

Verification: Describe how to confirm the procedure was successful. Include expected output or system behavior.

Troubleshooting: List common errors with their solutions. Format as problem-solution pairs for easy scanning.

Next steps: Link to related guides or suggest logical follow-up tasks.

API Reference Template

For each API endpoint, document these elements in order:

Endpoint title and description: A concise name and one-paragraph explanation of what the endpoint does and when to use it.

HTTP method and path: GET /api/v2/users/{userId} — always include the full path with path parameters clearly marked.

Authentication: Required authentication method and any specific permissions or scopes needed.

Parameters: Table with columns for name, type, required/optional, default value, and description. Group by parameter location (path, query, header, body).

Request body: JSON schema with example. Annotate each field with its type, constraints, and purpose.

Response: Success response with example JSON. Include HTTP status code. Document each field in the response body.

Error responses: Table of possible error codes with descriptions and resolution steps.

Code examples: Working examples in at least two popular languages (typically cURL and one SDK).

Troubleshooting Guide Template

Structure troubleshooting documentation for quick problem resolution:

Symptom-based organization: Organize by what the user observes ("Error 403 when accessing dashboard") not by the technical cause. Users search based on symptoms, not root causes.

Each entry should include: Symptom (what the user sees), Cause (why it happens — briefly), Solution (step-by-step fix), and Prevention (how to avoid recurrence, if applicable).

Prioritize by frequency: List the most common issues first. Use analytics and support ticket data to determine ordering.

Formatting Standards Cheatsheet

Code and Technical Elements

Inline code: Use code formatting for file names (config.yaml), commands (npm install), function names (getUser()), parameter names (maxRetries), environment variables (API_KEY), HTTP methods (GET, POST), status codes (200 OK, 404 Not Found), and keyboard keys (Enter, Ctrl+C).

Code blocks: Use fenced code blocks with language identifiers for syntax highlighting. Always include complete, runnable examples — not fragments. Add comments only to explain non-obvious parts. Test every code example before publishing.

Placeholders: Use angle brackets for values the user must replace: <your-api-key>, <project-name>, <server-url>. Be descriptive — <your-api-key> is better than <key>. Always explain where the user can find the actual value.

Lists and Tables

Numbered lists: Use for sequential steps or ranked items. Each item should start with an imperative verb for procedures. Keep list items parallel in structure.

Bulleted lists: Use for non-sequential items, features, or options. Limit to 7-9 items when possible. If a list exceeds 10 items, consider grouping into subcategories.

Tables: Use for structured data with consistent attributes. Always include a header row. Left-align text, right-align numbers. Keep cell content concise — if cells contain paragraphs, consider a different format.

Headings and Hierarchy

H1: Document title only. One per page. Should match or closely resemble the page title in navigation.

H2: Major sections. Use for the primary organizational divisions of your content. A user scanning H2 headings should understand the document's overall structure.

H3: Subsections within H2 sections. Use for detailed breakdowns of a major topic.

H4 and below: Use sparingly. If you need H4 headings frequently, consider restructuring your content into separate pages. Deep nesting makes documents harder to navigate.

Heading text: Use sentence case ("Configure your environment" not "Configure Your Environment"). Be specific and descriptive. A heading should tell the reader exactly what the section contains.

Writing Numbers and Units

General rule: Spell out numbers zero through nine; use numerals for 10 and above. Always use numerals with units (5 GB, 3 seconds, 2 CPUs). Use numerals in technical contexts regardless of size (port 8, version 2, step 3).

Units: Use standard abbreviations with a space between the number and unit (10 MB, 500 ms, 24 hours). Use binary prefixes for computing storage (KiB, MiB, GiB) when precision matters, or decimal prefixes (KB, MB, GB) for general audiences.

Ranges: Use an en dash without spaces for number ranges (10–20, pages 5–12). In technical contexts, consider being explicit ("from 10 to 20" or "between 10 and 20") to avoid ambiguity.

Accessibility Cheatsheet

Alt text for images: Describe what the image shows and why it matters. For screenshots, describe the UI state and any highlighted elements. For diagrams, summarize the relationships depicted. Keep alt text under 150 characters when possible.

Link text: Use descriptive link text that makes sense out of context. "Learn more about authentication" is better than "click here." Screen readers often present links in a list, so each link should be self-explanatory.

Color independence: Never convey information through color alone. If you use red text for errors, also include an error icon or prefix. Ensure sufficient contrast ratios (4.5:1 minimum for normal text, 3:1 for large text).

Document structure: Use proper heading hierarchy — screen readers use headings for navigation. Don't skip heading levels (H2 to H4 without H3). Ensure tables have proper header rows marked up semantically.

Review and Quality Checklist

Use this checklist before publishing any documentation:

Accuracy: Have you tested every procedure yourself? Are all code examples verified and runnable? Do screenshots match the current UI? Are version numbers and system requirements current?

Completeness: Are prerequisites clearly listed? Does every procedure include verification steps? Are error scenarios documented? Are all required parameters documented for API endpoints?

Clarity: Is the document written in active voice? Are sentences concise (under 25 words when possible)? Is jargon defined on first use? Would a new team member understand the content?

Consistency: Does the document follow your style guide? Are terms used consistently throughout? Do headings follow the same pattern? Are formatting conventions applied uniformly?

Navigation: Can users find what they need by scanning headings? Are related documents cross-linked? Does the table of contents accurately reflect the content? Are anchor links working correctly?

Keep this collection of cheatsheets within reach during your writing sessions. As your documentation practice matures, customize these templates and standards to match your specific product, audience, and organizational requirements. The best style guide is one that your entire team actually follows — start with these foundations and adapt them to fit your needs.