Skip to main content

​
Kive Docs Writing Guide

​
1) Purpose

Clear, fast, useful. Every page helps a user understand and do a specific job.

​
2) Page types

  • How-to: accomplish a task end-to-end.
  • Concept: what/why; mental model; when to use.
  • Reference: options/settings, short and scannable.
  • Troubleshooting: symptoms → fixes.

​
3) Page structure (flexible, minimal)

  1. Title (user language).
  2. Overview (2–4 sentences: purpose + when to use).
  3. Body: sections as needed.
    • Steps (numbered) for sequences.
    • Options/Details (bullets) for parallel info.
    • Callouts for notes/tips/warnings (1–3 sentences).
  4. See also (2–4 links).
Do not force sections. Remove what isn’t needed.

​
4) Voice

  • Direct, friendly, concise. Use you/your.
  • Active verbs. Short sentences.
  • Use exact UI labels in bold on first mention.

​
5) Narrative ↔ Lists

  • Start each section with 1–2 sentences before any list.
  • No back-to-back lists; add a bridging sentence.
  • Lists: 3–7 items. Split if longer.
  • If a bullet needs >1 sentence, make it a short paragraph.

​
6) Steps

  • One action per step, start with a verb.
  • Keep branches out of steps; create sub-sections (“If using uploads…”).

​
7) Options/Reference

  • Bullets only. Order: most used → advanced.
  • Mark plan gating inline: Pro/Enterprise.

​
8) Callouts

  • Note (limits, prerequisites), Tip (best practice), Warning (risk).
  • Keep to 1–3 sentences. Don’t stack multiple callouts.

​
9) Visuals

  • Add only when they clarify. Crop tight.
  • Caption every image. Place immediately after the mention.
  • Link key terms on first mention.
  • End with See also to adjacent jobs.

​
11) Tables

  • Use for keywords/short fields only.
  • Never put long sentences or paragraphs in tables.

​
12) Terms & consistency

  • Define Kive-specific terms on first use or link Glossary.
  • Use consistent casing and the exact product wording.

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

  • Usefulness: Helps complete a real job. 10 = essential to success; 0 = things users would discover anyway (e.g., explaining exactly what’s on a page, even if that is already obvious or non-essential to the job in question).
  • Clarity: Easy to follow; unambiguous; correct labels/screens.
  • Natural flow: Reads like prose; lists are contextualized.
  • Actionability: Concrete steps; outcomes clear; errors covered.
  • Style & consistency: Tone, labels, headings, formatting.
  • Brevity: Keep it short and concise.
Weighted score (100): Usefulness 40, Clarity 25, Actionability 20, Flow 10, Style 5. Ship if ≥80. If Usefulness <7, rewrite or cut.

​
14) Pre-publish checklist

  • Run quality rubric check, be fair but high-critical.
  • Question not just individual lines, but entire sections. If a section does not meet the quality rubric, cut it.
  • Reads end-to-end in <3 minutes.

​
15) 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 that keep empty sections.