​

FormHug Docs Writing Guide

​

1. Brand & Voice

​

Product Name

​

Standard Terminology

​

Tone

• Clear and direct. Say what something does in the first sentence.
• Confident, not salesy. Describe capabilities factually; don’t oversell.
• Friendly, not casual. Professional but approachable. No slang.
• Active voice. “Click Publish” not “The Publish button should be clicked.”
• Present tense. “FormHug saves your progress” not “FormHug will save your progress.”

​

2. Frontmatter

---
title: Booking Forms
description: Set up time slots, availability rules, and confirmation emails for your booking form
icon: calendar
---

​

title

• 3–6 words, Title Case
• Lead with the primary keyword (what users search for)
• No punctuation at the end

​

description

• One complete sentence, 100–160 characters
• Contains the primary keyword naturally
• Describes what the user can do or learn on the page
• No period at the end is fine; consistency either way

​

icon

• Always include. Use FontAwesome icon names.
• Pick icons that are semantically related, not just decorative.

​

3. Page Structure

​

No H1 after frontmatter

​

Standard layout

[Lead sentence or two]

## Section One

[Content]

## Section Two

[Content]

## Related   ← always end with this

​

Lead sentence

• 1–2 sentences immediately after frontmatter
• Answers: what does this feature do and why does it matter?
• Contains the page’s primary keyword naturally

The **Booking** scene lets you collect appointments online. Submitters pick from available time slots, and FormHug handles availability rules and confirmation emails automatically.

​

Headings

• H2 (##) — major sections. Aim for 3–5 H2s per page.
• H3 (###) — sub-sections within an H2. Use sparingly.
• Write headings as noun phrases for reference pages (“Available Field Types”) and verb phrases for how-to pages (“Add a Field”).
• Include keywords in H2 headings where natural.

​

Ending every page

## Related

<CardGroup cols={2}>
  <Card title="Booking Form Guide" icon="graduation-cap" href="/guides/use-cases/booking-form">
    Step-by-step tutorial
  </Card>
  <Card title="Form Notifications" icon="bell" href="/features/settings/notifications">
    Set up confirmation emails
  </Card>
</CardGroup>

​

4. Writing Style

​

Sentences

• Keep sentences under 25 words.
• One idea per sentence.
• Start with the subject, not a subordinate clause.

​

Paragraphs

• 2–4 sentences max per paragraph.
• One topic per paragraph.
• Leave a blank line between paragraphs in MDX.

​

Bold and emphasis

• Bold (**text**) for: UI labels, product terms on first mention, key concepts.
• Italic (*text*) only for: genuine emphasis, or book/product titles. Use sparingly.
• Never use bold just for decoration.

​

Lists

• Use a bulleted list when order doesn’t matter and items are short (< 1 line each).
• Use a numbered list only when order matters (steps, ranked items).
• Use the <Steps> component (not a numbered list) for multi-step how-to instructions.
• Keep list items parallel in structure.
• If a list has only 2 items, consider writing it as a sentence instead.

​

Numbers

• Spell out one through nine: “three fields”, “two steps”.
• Use digits for 10 and above, and always for UI-specific values: “30+ field types”, “5-star rating”.

​

5. Mintlify Components

​

Steps example

<Steps>
  <Step title="Open Settings">
    Click the gear icon in the top-right corner of the editor.
  </Step>
  <Step title="Enable Notifications">
    Toggle **Email Notifications** on, then enter the recipient address.
  </Step>
</Steps>

​

Callout guidelines

• <Tip>: “Try using AI Builder to generate your first draft in seconds.”
• <Note>: “This setting only applies to forms with the Quiz scene enabled.”
• <Warning>: “Deleting a form is permanent and cannot be undone.”

​

6. SEO / GEO Guidelines

​

Titles and descriptions

• Include the primary keyword in the title (preferably the first word or two).
• Write description as a complete, useful sentence — AI assistants often use this verbatim as a summary.

​

Content structure for GEO

• Lead with the answer. Don’t bury the main point. AI retrieval systems favor pages that answer the question in the first 1–2 sentences.
• Use complete sentences in important sections. Avoid fragment-only bullet lists where prose works better.
• Write factual, specific statements. “FormHug supports 30+ field types” is more citable than “FormHug has many fields.”
• H2 headings should be answerable questions or clear noun phrases. This helps AI match headings to user queries.

​

Internal linking

• Every page must link to at least 1 related page (via card at the end).
• Feature pages should link to their corresponding guide, and vice versa.

​

Don’t

• Don’t keyword stuff. Write for humans; search engines follow.
• Don’t use vague headings like “Overview”, “Details”, or “More Information” — be specific.
• Don’t repeat the same phrase 5+ times in a short page.

​

7. Page Templates

​

Feature reference page

[Lead: what this feature is and what it enables — 1–2 sentences]

## [What It Does / Key Capabilities]
[Table or bullet list of capabilities]

## [How to Use It / How It Works]
[Steps component or prose]

## [Options / Settings]
[Table of available options]

## Related
[CardGroup with 1–2 related pages]

​

How-to guide

[Lead: what the user will accomplish by following this guide]

## Before You Start
[Prerequisites, if any — skip if none]

## [Step-based H2 sections or single Steps component]

## Tips
[2–4 Tip callouts or bullets]

## Related
[Card or CardGroup]

​

FAQ page

[Lead sentence]

## [Topic Group]
<AccordionGroup>
  <Accordion title="Question?">Answer.</Accordion>
</AccordionGroup>

## [Topic Group]
...

## Need More Help?
<Card ... />

​

8. Common Mistakes to Avoid