Skip to main content

​
Documentation Audit — Reduce, Tighten, Simplify

Branch: docs/18-brand-voice-audit Issue: #18 Status: Pre-work (deploy after v1.10.1 release)

​
Philosophy

Users shouldn’t need docs. The app should be obvious. Docs exist as backup + SEO/marketing. Fewer pages, tighter copy. If it needs a doc page, maybe it should be in the app.

​
Goals

  1. Reduce page count — Merge overlapping content, delete redundant pages
  2. Move to app — Onboarding, tips, templates belong IN Cleft, not docs
  3. Deep links — Every doc links to the feature in-app (cleft://)
  4. Tighten copy — Cut 30-50% without losing meaning
  5. One brand voice — Direct, warm, confident
  6. SEO value — Pages that rank and convert
  7. Future-proof — Blog content moves to Next.js site later

​
Current State vs Target

CategoryCurrentTargetAction
Core85-6Merge
Feature docs2510-12Consolidate
Persona guides83-4Merge into archetypes
Cookbook125-6Best recipes only
Integrations4820-25Template-ize
Trust/legal88Keep (required)
Total~109~55-65-40-50%

​
Page-by-Page Decisions

​
Legend

  • ✅ Keep — Essential, tighten copy only
  • 🔀 Merge — Combine with another page
  • 🗑️ Delete — Redundant or unnecessary
  • 📝 Blog — Move to future Next.js blog (SEO/marketing content)

​
Core Pages (Landing + Onboarding)

PageDecisionAction
readme.mdx✅ KeepTighten, first impression
getting-started.mdx✅ KeepCritical path, simplify
how-cleft-works.mdx🔀 Merge→ Into getting-started
features.mdx✅ KeepSEO gold, tighten
upgrade-to-plus.mdx✅ KeepConversion page
faq.mdx✅ KeepSupport deflection
whats-new-v110.mdx🗑️ DeleteRedundant with changelog
resources/changelog.mdx✅ KeepAlready tight
Result: 8 → 6 pages

​
Feature Documentation

​
Recording & Transcription (6 → 3)

PageDecisionAction
recording-voice-notes.mdx✅ KeepCore feature
live-transcription.mdx🔀 Merge→ Into recording-voice-notes
editing-transcriptions.mdx🔀 Merge→ Into editing-notes
viewing-transcripts.mdx🔀 Merge→ Into editing-notes
languages.mdx✅ KeepSEO value (57 languages)
download-original-audio.mdx🔀 Merge→ Into recording-voice-notes

​
Notes & Organization (8 → 4)

PageDecisionAction
editing-notes.mdx✅ KeepCore (absorbs transcription pages)
formatting-notes.mdx🔀 Merge→ Into editing-notes
advanced-formatting.mdx🔀 Merge→ Into editing-notes
searching-notes.mdx✅ KeepSpotlight = SEO
syncing-notes.mdx✅ KeepCommon support question
using-folders.mdx🔀 Merge→ Into editing-notes
copying-notes.mdx🔀 Merge→ Into FAQ or delete
shareable-links.mdx✅ KeepPlus feature

​
Platform Pages (6 → 3)

PageDecisionAction
ios.mdx✅ KeepPlatform landing
ipados.mdx🔀 Merge→ Into ios.mdx (same OS)
macos.mdx✅ KeepPlatform landing
apple-watch.mdx✅ KeepUnique platform
keyboard-shortcuts.mdx🔀 Merge→ Into macos.mdx
widgets-and-action-button.mdx🔀 Merge→ Into ios.mdx

​
Settings & Account (4 → 2)

PageDecisionAction
settings.mdx✅ KeepReference
custom-instructions.mdx✅ KeepPlus feature, SEO
account-setup.mdx🔀 Merge→ Into getting-started
restore-account-and-purchases.mdx🔀 Merge→ Into FAQ
Feature docs result: 25 → 12 pages

​
Persona Guides (8+ → 3 Landing Pages)

Strategy: Keep personas in Mintlify temporarily, migrate to Webflow later. Issues: #23, #24, #25

​
New Landing Pages (Create)

PagePathIssueStatus
ADHD users/user-guides/for-adhd.mdx#23Planned
Executives/user-guides/for-executives.mdx#24Planned
Students/user-guides/for-students.mdx#25Planned

​
Existing Pages (Consolidate)

PageDecisionAction
who-uses-cleft.mdx✅ KeepIndex → links to new pages
adhd-coach.mdx🔀 Merge→ Into for-adhd.mdx
neurodivergent-professional.mdx🔀 Merge→ Into for-adhd.mdx
consultants.mdx🔀 Merge→ Into for-executives.mdx
overwhelmed-organizer.mdx🗑️ DeleteToo generic
Other personas📝 BlogMove to blog when ready
Persona result: 8+ scattered pages → 3 strong landing pages

​
Cookbook & Workflows (12 → 5)

Problem: Too many recipes that could be templates in the app.
PageDecisionAction
the-cookbook.mdx✅ KeepIndex
workflow-recipes.mdx🔀 Merge→ Into the-cookbook
meeting-notes-system.mdx✅ KeepHigh value
task-management.mdx🔀 Merge→ Into FAQ or delete
knowledge-management.mdx📝 BlogSEO content
collaboration-patterns.mdx🗑️ DeleteNot a Cleft focus
batch-processing.mdx🔀 Merge→ Into cookbook
prompt-templates.mdx🔀 Merge→ Into custom-instructions
custom-instructions-library.mdx✅ KeepHigh value
voice-command-tips.mdx🔀 Merge→ Into recording-voice-notes
integration-workflows.mdx🔀 Merge→ Into integrations overview
Cookbook result: 12 → 5 pages

​
Integrations (48 → 20-25)

Problem: One page per zap/shortcut is excessive. Template-ize.

​
Strategy

  1. One overview per integration — Notion, Obsidian, Zapier, Shortcuts
  2. Templates gallery — Single page listing all Zapier templates
  3. Shortcuts gallery — Single page listing all shortcuts
  4. Delete individual pages — Zap/shortcut detail pages are redundant

​
Keep (Native Integrations)

PageDecisionWhy
integrations/overview.mdx✅ KeepIndex
integrations/notion/overview.mdx✅ KeepNative integration
integrations/obsidian/overview.mdx✅ KeepNative integration
integrations/apple-notes/overview.mdx✅ KeepNative integration
integrations/apple-shortcuts/overview.mdx✅ KeepPlatform feature
integrations/zapier/templates.mdx✅ KeepGallery page
All individual zap pages merge into zapier/templates.mdx:
  • todoist/zaps/*.mdx → Gallery card
  • asana/zaps/*.mdx → Gallery card
  • clickup/zaps/*.mdx → Gallery card
  • github/zaps/*.mdx → Gallery card
  • jira/zaps/*.mdx → Gallery card
  • etc.
All individual shortcut pages merge into apple-shortcuts/gallery.mdx:
  • Individual shortcut detail → Gallery card with download link
Integrations result: 48 → ~20 pages

​
Trust/Legal (8 → 8)

Keep all. Legal requirement, formal voice appropriate.
PageDecision
trust/overview.mdx✅ Keep
trust/privacy-policy.mdx✅ Keep
trust/terms-of-service.mdx✅ Keep
trust/data-processing-agreement-dpa.mdx✅ Keep
trust/accessibility-statement.mdx✅ Keep
trust/vendors.mdx✅ Keep
trust/data-rights.mdx✅ Keep
trust/security.mdx✅ Keep
Trust result: 8 → 8 pages (no change)

​
📊 Comparisons & SEO Content

Strategy: Neutral decision menus, not sales pitches. Public info only. Issues: #20, #21, #22

​
Philosophy

Not a sales pitch. A neutral menu for users to decide. These tools may complement each other in a workflow. Public information only — no opinions that could cause issues.

​
Comparison Pages (Create)

PagePathIssueSprint
Cleft vs Otter/user-guides/compare/cleft-vs-otter.mdx#20Next
Cleft vs AudioPen/user-guides/compare/cleft-vs-audiopen.mdx#21Next
Voice Notes Apps 2025/user-guides/compare/voice-notes-apps-2025.mdx#22Next

​
Format: Decision Menu

If you need…Consider…
Local/privateCleft, Whisper Memos
MeetingsOtter, Fireflies
Web accessAudioPen, Otter
Apple ecosystemCleft

​
Workflow Combos

Acknowledge tools work together — builds trust:
  • “Otter for meetings + Cleft for personal notes”
  • “AudioPen on web + Cleft on mobile”

​
🚀 Migrate to App (Issues for cleft-notes)

These doc pages exist because the feature isn’t obvious in-app. Fix the app, delete the doc.
Doc PageShould Be In AppDeep LinkIssue
getting-started.mdxOnboarding flowcleft://onboardingCreate
custom-instructions.mdxIn-app templates librarycleft://settings/instructionsCreate
custom-instructions-library.mdxTemplate picker in appcleft://templatesCreate
keyboard-shortcuts.mdxHelp menu (⌘?)cleft://help/shortcutsCreate
voice-command-tips.mdxTooltip during recordingN/ACreate
prompt-templates.mdxTemplate gallery in appcleft://templatesMerge w/ above
faq.mdxIn-app help / support chatcleft://helpFuture
Every doc page should have a “Try it now” button: 
<Card title="Try Custom Instructions" icon="wand" href="cleft://settings/instructions">
  Open in Cleft →
</Card>
Result: User reads doc → taps → lands in the feature. No friction.

​
Issues to Create (cleft-notes)

  1. In-app onboarding — Replace docs getting-started
  2. Template library UI — Browse/apply custom instructions in-app
  3. Help menu with shortcuts — ⌘? shows shortcuts overlay
  4. Deep link support — cleft:// URL scheme for all features
  5. Contextual tips — Tooltips that replace doc pages

​
Summary: The Reduction

CategoryBeforeAfterCut
Core86-25%
Feature docs2512-52%
Personas8+3-63%
Cookbook125-58%
Integrations4820-58%
Trust880%
Total~109~54-50%

​
Content Moves to Future Blog

  • Persona deep-dives (consultants, lawyers, creatives, etc.)
  • Workflow tutorials (knowledge management, daily routines)
  • SEO content that’s not core docs

​
Brand Voice Checklist

When editing each page:
  • Direct — No fluff, no “In order to…”
  • Warm — “We” and “you”, not “users” and “the system”
  • Confident — State facts, don’t hedge
  • Tight — Cut 30-50% without losing meaning
  • One term — “note” not “recording/transcript/note”

​
Future: Content Architecture

​
Universal Standard: Diátaxis Framework

Don’t reinvent the wheel. Follow Diátaxis — the industry standard:
TypeUser NeedOur LocationExample
TutorialLearningApp onboarding”Your first note”
How-toGoalBlog (future)“Meeting notes workflow”
ReferenceInformation/doc/*”Keyboard shortcuts”
ExplanationUnderstandingBlog (future)“How transcription works”

​
Our Three Layers (Applying Diátaxis)

LayerDiátaxis TypeLocationPurpose
AppTutorialCleft appLearning by doing
ReferenceReference/doc/*Quick answers
GuidesHow-to + ExplanationBlogWorkflows, understanding

​
Philosophy

  • App first — Tutorials belong in the app, not docs
  • Reference = backup — Quick answers for power users (boring, standard)
  • Guides = inspiration — Show what’s possible, not required reading
  • Too much docs = bad product — We ship solutions, not manuals
  • Don’t reinvent — Docs follow standards, product innovates

​
Platform Magic (Mac)

When user opens docs on Mac:
  1. Auto side-by-side — App + Safari tile automatically
  2. Deep link buttons — “Try it” opens the feature
  3. App Intents — Siri/Shortcuts integration with docs
  4. Scripts — Automator/AppleScript for power users
This isn’t AI magic — it’s platform magic. Using Mac’s native capabilities to make the experience feel crafted.

​
Web App (Future)

When web app ships:
  • Cross-platform reference (same docs work everywhere)
  • Different UX needs than native apps
  • May need its own documentation layer
  • But same philosophy: app teaches itself

​
Next.js Blog (Future)

  1. Move guides — Persona content, workflow tutorials
  2. SEO engine — Drives traffic to app
  3. Thought leadership — Voice-first productivity content
  4. Can’t do in Webflow — Need full control

​
Execution Plan

​
Phase 1: Audit (This PR)

  • Categorize all pages
  • Mark Keep/Merge/Delete/Blog
  • Review with team

​
Phase 2: Core Pages (After v1.10.1)

  • Tighten 6 core pages
  • Merge how-cleft-works → getting-started
  • Delete whats-new-v110

​
Phase 3: Feature Consolidation

  • Merge transcription pages → editing-notes
  • Merge platform detail → platform landing pages
  • Consolidate settings/account pages

​
Phase 4: Integration Cleanup

  • Merge zap pages → gallery
  • Merge shortcut pages → gallery
  • Delete redundant detail pages

​
Phase 5: Blog Migration (When Next.js Ready)

  • Move persona content
  • Move workflow tutorials
  • Redirect old URLs
Last Updated: 2025-12-02