Skip to main content

​
TestDino Documentation Writing Guidelines

​
Role

Senior technical writer documenting developer tools and SaaS platforms for real engineering workflows.

​
Audience

Engineers, QA leads, and CTO-level readers who want accurate information quickly.

​
Writing Goals

  • Focus on how things are actually used
  • Prioritize clarity over completeness
  • Optimize for fast scanning
  • Reduce cognitive load
  • Assume the reader is technical but time-constrained

​
Tone and Style

DoDon’t
Calm, neutral, confidentMarketing or promotional phrasing
Developer-first languageHype or buzzwords
Short sentencesLong, elaborate sentences
Present tensePast or future tense
Consistent terminologyVarying terms for same concept
Nouns and clear actionsFiller phrases

​
Content Principles

  1. Start with what the feature does - First sentence states the purpose
  2. Make assumptions explicit - State prerequisites clearly
  3. Explain why steps matter - Context helps retention
  4. Show practical usage - Real examples over abstract explanations
  5. Keep examples minimal - One clear example over many
  6. Don’t invent features - Document only what exists

​
Structure Guidelines

ElementGuideline
HeadingsShort, descriptive, only when they improve readability
ParagraphsKeep short, avoid walls of text
Quick ReferenceAdd at top for long pages with links to sections
TablesUse for comparisons, options, quick lookups
Code blocksInclude filename comment, keep minimal
Related cards2-4 cards linking to related content

​
Language Rules

RuleExample
No emojis✗ 🚀 → ✓ (use sparingly in tables only)
No em dashesRephrase sentences instead
No exclamation marksExcept in code/commands
No filler phrases”simply”, “just”, “easily”, “actually”
No unnecessary adjectives”powerful”, “robust”, “seamless”
No vague words”might”, “could”, “should” → direct statements
No “helps you”, “lets you”, “allows you to”Direct action instead

​
SEO Best Practices

​
Frontmatter

---
title: "Short, Descriptive Title"
description: "Action-oriented description under 160 characters."
icon: "relevant-icon"
keywords: ['primary keyword', 'secondary keyword', 'long-tail keyword']
difficulty: beginner | intermediate | advanced
og:image: "logo/og-image.svg"
---

​
Keywords

  • Include 5-7 relevant keywords
  • Mix primary terms with long-tail variations
  • Include product name + feature combinations

​
Component Usage

​
Quick Reference Tables

Add at top of long pages with links: 
| Item | Description |
| :--- | :--- |
| [Feature](/path) | Brief description |

​
Steps Component

Use for sequential setup: 
<Steps>
  <Step title="Step Name">
    Content here
  </Step>
</Steps>

​
Tabs Component

Use for platform/tool variations: 
<Tabs>
  <Tab title="Option A">Content</Tab>
  <Tab title="Option B">Content</Tab>
</Tabs>

​
Images

  <img src="url" alt="Descriptive alt text explaining what's shown" />

​
Videos

  <video controls loop preload="metadata" src="url" alt="Description" />

<CardGroup cols={2}>
  <Card title="Title" icon="icon-name" href="/path">
    Brief description
  </Card>
</CardGroup>

​
Notes and Warnings

<Note>Helpful information</Note>
<Warning>Important caution</Warning>
<Tip>Pro tip</Tip>

​
Cross-Linking Strategy

WhenLink to
Mentioning a featurePlatform documentation page
CLI flags/cli/nodejs
Setup stepsRelated guide
Quick reference itemsDetailed section or page
PrerequisitesSetup guide

​
Quality Bar

Documentation should read like:
  • Playwright docs
  • GitHub docs
  • Stripe docs
  • Vercel docs
Ready to publish without editing.

​
Checklist Before Publishing

  • First sentence states what feature does
  • No marketing language or filler
  • Short paragraphs and sentences
  • Tables for options/comparisons
  • Images with alt text
  • Quick reference at top (if long page)
  • Related cards at bottom
  • Cross-links to relevant pages
  • Keywords in frontmatter (5-7)
  • Description under 160 characters
  • No em dashes, exclamation marks, or emojis in prose