Skip to content

Contributing Documentation

This document shows how to change documentation correctly without breaking structure or style. It is written for anyone contributing to ConnectSoft's documentation site.

ConnectSoft documentation follows consistent style, structure, and patterns. This guide ensures contributions maintain quality and consistency.

Note

Documentation is built with MkDocs and Material for MkDocs. All documentation is in Markdown format with frontmatter metadata.

Types of Documentation

ConnectSoft documentation includes:

  • Conceptual - Architecture principles, design patterns, concepts
  • Reference - API references, glossary, FAQ
  • Guides - Getting started guides, role-based quickstarts, example projects
  • Playbooks - Sales playbooks, proposal templates, operational playbooks
  • Runbooks - Operations runbooks, incident management, monitoring
  • Meeting Notes - Meeting notes and decisions

Style and Structure Requirements

Documentation Style Guide

Follow the ConnectSoft Documentation Style Guide:

  • Tone - Professional, pragmatic, slightly friendly
  • Audience - Senior engineers, architects, product managers
  • Structure - Title, intro, clear headings, callouts
  • Callouts - Use callouts for notes, tips, warnings, important points

See: Documentation Style Guide for detailed style guidelines.

Brand & UI Kit

Follow ConnectSoft brand guidelines:

  • Colors - Use brand colors in diagrams and examples
  • Typography - Follow typography guidelines
  • Icons - Use consistent iconography

See: Brand & UI Kit for brand guidelines.

Structure Rules

  • One # Title - Each page has exactly one # title
  • Intro Paragraph - Immediately after title, add 1-3 sentence intro
  • Clear Headings - Use logical ## and ### headings
  • Callouts - Use callouts for key points (note, tip, important, warning)
  • Cross-Links - Link to related documents

Adding New Pages

Step 1: Create Markdown File

  • Location - Create .md file under appropriate folder
  • Naming - Use kebab-case naming (e.g., getting-started-with-factory.md)
  • Frontmatter - Add frontmatter with title, description, tags

Step 2: Follow Naming Convention

  • Kebab-Case - Use kebab-case for file names
  • Descriptive - Use descriptive names
  • Consistent - Follow existing naming patterns

Step 3: Update Navigation

  • mkdocs.yml - Update mkdocs.yml navigation
  • Location - Add to appropriate section
  • Order - Maintain logical order

Step 4: Add Content

  • Title - Add # title
  • Intro - Add 1-3 sentence intro
  • Sections - Add logical sections with ## headings
  • Callouts - Add appropriate callouts
  • Links - Add cross-links to related docs

Working with Navigation (mkdocs.yml)

  • Top-Level Sections - Major sections (Vision, Strategy, Factory, etc.)
  • Subsections - Nested sections for organization
  • Order - Maintain logical order

Adding to Navigation

  1. Find Section - Find appropriate section in mkdocs.yml
  2. Add Entry - Add entry with label and path
  3. Test - Test navigation locally
  4. Commit - Commit changes
  • Logical Grouping - Group related pages together
  • Clear Labels - Use clear, descriptive labels
  • Consistent Order - Maintain consistent order
  • Not Too Deep - Avoid nesting too deeply (max 3 levels)

Review Checklist

Use this checklist when reviewing documentation PRs:

Content Quality

  • Is the audience clear?
  • Is the purpose clear?
  • Is the content accurate?
  • Is the content complete?

Structure and Style

  • Does it have a single # title?
  • Does it have an intro paragraph?
  • Are headings logical and clear?
  • Are callouts used appropriately?
  • Is terminology consistent?
  • Are links correct?
  • Are cross-references helpful?
  • Are relative paths correct?
  • Do links work?

Diagrams and Examples

  • Are diagrams necessary and clear?
  • Are Mermaid diagrams valid?
  • Are examples accurate?
  • Are code examples formatted correctly?
  • Is the page in the right section?
  • Is the navigation entry clear?
  • Is the order logical?

Tip

Local Testing: Run mkdocs serve locally to preview documentation changes before committing. This helps catch navigation issues, broken links, and formatting problems early.