​

Kive Docs Writing Guide

​

1) What we publish (page types)

• How-to: Do one job end-to-end. Outcome-focused, with numbered steps.
• Concept: What/why; mental model; when to use. No steps unless very high level.
• Reference: Options/settings; short and scannable bullets, most used → advanced.
• Troubleshooting: Symptoms → fixes. Match error wording and include quick checks.

​

2) Information architecture (IA) and naming

• Top-level groups (order): Getting started → Creating with AI → Organize → Editing tools → Discover → Account & workspace → Guides → Troubleshooting.
• Page title formulas:
  • How-to: Verb + object (e.g., “Generate an image”, “Train a custom model”).
  • Concept: “What is X?” or “Intro to X”.
  • Reference: “X settings” or “Options for X”.
  • Troubleshooting: “Fix X” or “X: common issues”.
• URL slugs: hyphen-case, use verbs (e.g., generate-an-image).
• One job per page: If you feel the urge to add “and”, split the page.

​

3) Page skeletons (use as-is)

​

How-to page (narrative-first)

# Generate an image

[Optional hero image]

Write a friendly 2–4 sentence intro that sounds like you’re showing a colleague how to do it. Use contractions. Mention the core UI entry point in **bold** on first use.

## Before you start
Write 1–2 sentences. If needed, add a short bullet list of prerequisites (account, plan, permissions).

## Steps
Start each step with a verb. Keep to 1–3 short sentences. Add an image only if it removes ambiguity.

## Options
Introduce in 1 sentence. Use 3–5 bullets, ordered most-used → advanced. Mark plan gating inline (Pro/Enterprise).

## Tips
Add 1–3 short tips in prose (not a long list). Start with “Tip:”.

## See also
1–3 links to adjacent jobs and key concepts.

​

Concept page (analogy-friendly)

# What is a block?

[Optional hero image]

Open with a conversational 2–4 sentence mental model. Prefer analogies (like LEGO). Use contractions. Avoid bullets until after the first paragraph.

## Key ideas
Use short paragraphs (2–4 lines). If you must, keep bullets to ≤5 and ≤1 sentence each.

## When to use
Describe typical situations vs alternatives in 3–5 sentences.

## Related actions
Link to the core how-to pages.

​

Reference page

# Generate image settings

One sentence on scope. No steps.

## Quality
* Setting → effect (keep to one line).

## Aspect ratio
* Options listed most-used → advanced.

## Limits
* Include plan gating and boundaries.

​

Troubleshooting page

# Fix blurry outputs

One sentence describing the symptom in user language.

## Quick checks
* 3–5 fastest things to try first.

## Likely causes and fixes
* Cause → Fix (1–2 sentences each).

## Still stuck?
* How to contact support, what logs or IDs to include.

​

4) Voice and tone (must-do)

• Use you/your. Present tense. Active verbs.
• Use exact UI labels in bold on first mention.
• Short sentences. Prefer plain words over jargon. Use contractions.
• Make it sound like you’re talking to one person. Friendly but precise.
• Explain why when it helps a decision; otherwise keep moving.

​

5) Headings and section rules

• H1 is the page title. Use H2 for sections. Avoid H4+.
• Max 5 sections per page. Each section starts with 2–4 sentences before any list.
• Don’t stack lists back-to-back — add a bridging sentence.
• Keep Steps to ≤10 actions. If more, split into sub-jobs.

​

6) Lists, steps, and options

• One action per step; start with a verb.
• Options/Reference: bullets only; most used → advanced.
• Bullets are a last resort. Prefer short paragraphs; if you use bullets, keep them ≤5 and ≤1 sentence each.

​

7) Visuals

• Add only when they remove confusion. Crop tight.
• Caption every image. Place immediately after the mention.
• Use 1–3 images per page for typical how-tos; more only when essential.

​

8) Callouts

• Use sparingly: Note (limits/prereqs), Tip (best practice), Warning (risk).
• 1–3 sentences. Don’t chain multiple callouts.

​

9) Cross-links

• Link key terms on first mention.
• End with a short See also linking to adjacent jobs.

​

10) Consistency and terminology

• Use product wording and casing exactly as in the UI.
• Define Kive-specific terms on first use or link to Glossary.

​

11) Length, readability, and structure

• Read end-to-end in under 3 minutes for most pages.
• Keep paragraphs to 2–4 lines. Break up walls of text. Avoid back-to-back lists.
• At least 60% of the page should be prose paragraphs (not lists, tables, or callouts).
• Avoid nested conditions; create a subsection instead.

​

12) Naming guide with examples

• Prefer these names:
  • “Generate an image” (not “AI Image Generation”).
  • “Generate a video” (not “AI Video Generation”).
  • “Write effective prompts” (not “Prompts & Style References”).
  • “Train a custom model” (not “AI Models & Custom Training”).
  • “Use Organize boards” (not “Library & Boards Overview”).
  • “Upload assets” (not “Add assets”).
  • “Manage assets” (keep).
  • “Search your library” (not “Search”).
  • “Use the Discover page” (keep but consider “Discover inspiration”).
  • “Save inspiration” (not “Save Content”).
  • “Account settings”, “Workspace settings”, “Manage members”, “Billing”, “Custom properties setup” (keep).
  • “Credits & limits: FAQ” (not “Credits FAQ”). etc.

​

13) Optimising for GEO

• Don’t skip heading levels (H1 → H2 → H3)
• Give images descriptive alt text
• Link to related concepts to help AI understand relationships
• Answer questions directly - write content that addresses specific user questions
  1. Begin sections with the main takeaway
  2. Use descriptive headings that match common queries
  3. Break complex topics into numbered steps (e.g. 1. 2. 3. etc.)

​

14) Golden examples (patterns to imitate)

• Start with a friendly 2–4 sentence overview that says what and when.
• Use short, imperative steps; add small tips inline.
• End sections with a nudge (“Learn more about X →”) when relevant.

​

15) Quality rubric (0–10 each; aim ≥8)

• Usefulness: Helps complete a real job; essential to success. (40%)
• Clarity: Correct labels/screens; unambiguous. (25%)
• Actionability: Concrete steps; outcomes clear; common errors covered. (20%)
• Flow: Reads like prose; lists are contextualized. (10%)
• Style: Tone, labels, headings, formatting. (5%)

​

16) Pre-publish checklist (blockers if unchecked)

• Page matches a single type (How-to / Concept / Reference / Troubleshooting).
• Title follows naming formula (e.g., Verb + object for how-to).
• Intro is 2–4 sentences and explains what/when in user language.
• Sections ≤5, each introduced with 2–4 sentences before any list.
• Steps are imperative, ≤10 actions, one action per step.
• Images are cropped, captioned, and placed after the mention.
• “See also” includes 1–3 adjacent jobs.
• Reads end-to-end in under 3 minutes.
• ≥60% of the page is prose (not lists/tables/callouts).

​

17) Anti-patterns (cut or fix)

• Wall-to-wall bullets with no prose.
• Explaining obvious UI (“Click Next to go next”).
• Listing every toggle without saying why or when.
• Repeating the same info across pages (link instead).
• Over-templated pages with empty sections.