Skip to content

📖 GetCimple Documentation Guide

This guide consolidates our documentation standards, style rules, emoji usage, and maintenance practices into one practical resource.

🎯 Documentation Principles

As a 3-person startup, we keep documentation:

  • Simple: Write only what's needed
  • Practical: Focus on actionable content
  • Consistent: Use the same patterns everywhere
  • Maintainable: Easy to update as we grow

📁 File Structure & Naming

File Naming

Always use kebab-case:

  • ✅ user-onboarding-guide.md
  • ❌ UserOnboardingGuide.md
  • ❌ user_onboarding_guide.md

Required Frontmatter

Every document needs:

---
title: 'Clear Document Title'
description: 'What this document does in one sentence'
category: Business/Architecture/Features/etc
last_updated: 'YYYY-MM-DD'
status: active/draft/deprecated
---

Document Structure

  • Maximum 4 heading levels (H1 through H4)
  • Lead with most important info
  • Use bullet points for lists over 3 items
  • Keep documents under 3 pages when possible

✍️ Writing Style

Language Guidelines

  • Write like you're helping a teammate
  • Use "we" and "you" instead of passive voice
  • Choose simple words over complex ones
  • Keep sentences short (under 15 words when possible)

Be Direct

  • ✅ "Click the Save button"
  • ❌ "The user should proceed to click the Save button"

Write for Your Audience

  • Directors: Focus on outcomes and oversight
  • Management: Focus on implementation and reporting
  • IT Staff: Focus on technical requirements

🎨 Emoji Usage

Core Rules

  1. One emoji per heading maximum
  2. Place at beginning with space: # 📋 Overview
  3. Use consistently - same emoji = same concept
  4. Professional context - limited, meaningful usage

Standard Emojis

Document Structure:

  • 📋 Overview/Summary
  • 🎯 Goals/Objectives
  • ✅ Requirements/Checklist
  • 🚀 Getting Started
  • 📊 Metrics/Analytics
  • 🔧 Configuration
  • ⚠️ Important Notes
  • 💡 Tips/Best Practices

Status Indicators:

  • ✅ Complete/Success
  • ❌ Error/Failure
  • ⏳ In Progress
  • 🚧 Under Construction

Stakeholders:

  • 👤 Individual User
  • 👥 Team/Group
  • 🏢 Organization
  • 💼 Board/Executive

Technical:

  • 💻 Code/Development
  • 🔒 Security
  • 🔄 Process/Workflow
  • 📁 Files/Documents

🔗 Cross-Linking

Use relative paths from docs root:

See [Authentication Guide](../05-architecture/authentication-mvp.md)
  • Verify links work before committing
  • Update links when moving files
  • Use descriptive text not "click here"
  • Link to sections with anchors when helpful

📏 Consistency Rules

Terminology

Keep these consistent everywhere:

  • GetCimple (not Get Cimple or getcimple)
  • directors (not board members)
  • management teams (not managers)
  • governance oversight (not technical security)
  • shadcn-svelte (not shadcn/ui)

Common Patterns

  • Lists: Use - for bullets, not * or +
  • Code blocks: Always specify language
  • Tables: Include header separator
  • Links: Use reference style for repeated URLs

🛠️ Maintenance

Regular Tasks

  • Weekly: Run npm run docs:check:links
  • Before commits: Run npm run format:docs
  • Monthly: Review and update outdated content

Quality Checks

# Format all docs
npm run format:docs

# Check for broken links
npm run docs:check:links

# Check consistency
npm run docs:check:consistency

When to Update Docs

  • Immediately: Breaking changes, security issues
  • Within a day: New features, process changes
  • Within a week: Minor updates, clarifications

📊 Documentation Metrics

Track these simple metrics:

  • Doc coverage: Every feature has documentation
  • Freshness: No doc older than 3 months without review
  • Accessibility: New team member can onboard in < 1 day
  • Feedback: Users can find what they need quickly

🚀 Quick Start Templates

New Feature Documentation

---
title: 'Feature Name'
description: 'What this feature does'
category: Features
last_updated: 'YYYY-MM-DD'
status: active
---

# 🎯 Feature Name

## Overview

What problem this solves in 1-2 sentences.

## How It Works

Simple explanation of the feature.

## Getting Started

1. First step
2. Second step
3. Third step

## Common Use Cases

- Use case 1
- Use case 2

## Troubleshooting

Common issues and solutions.

Process Documentation

---
title: 'Process Name'
description: 'What this process accomplishes'
category: Business
last_updated: 'YYYY-MM-DD'
status: active
---

# 🔄 Process Name

## Purpose

Why this process exists.

## When to Use

Specific triggers or scenarios.

## Steps

1. **Step One**: Description
2. **Step Two**: Description
3. **Step Three**: Description

## Outcomes

What success looks like.

Remember: Good documentation helps your future self and teammatest. Keep it simple, keep it current, keep it useful!