CADit User Documentation Framework

This document establishes the guidelines, tone, structure, and content types for all CADit user documentation. Follow these standards to ensure a consistent, helpful user experience.

1. Audience

Primary Audience

Hobbyists and makers who want to create 3D printable designs
Beginners with little to no CAD experience
Educators and students learning 3D design concepts
Casual users looking for quick, intuitive design tools

Secondary Audience

Intermediate users wanting to leverage advanced features like Code Mode
Developers using CADit scripts and GitHub integration
Content creators publishing designs to the library

Assumptions About Readers

Familiar with basic computer use (file management, web browsing)
May not have prior CAD or 3D modeling experience
Want to accomplish tasks, not learn theory
Value clear, scannable content over exhaustive detail

2. Tone and Voice

Core Principles

Be direct and helpful

Get to the point quickly
Tell users what to do, not what they could do
Prefer active voice: "Click the Rectangle tool" not "The Rectangle tool can be clicked"

Be confident but not condescending

Write as a knowledgeable guide, not a lecturer
Avoid over-explaining simple concepts
Trust the reader to follow clear instructions

Stay practical

Focus on accomplishing tasks
Skip theoretical background unless it helps the user
Provide concrete examples

What to Avoid

No unnecessary emojis - Emojis are acceptable only when they genuinely aid comprehension (e.g., illustrating a concept). Never use emojis for emphasis, decoration, or "friendliness"
No jargon without explanation - If a technical term is necessary, define it briefly
No implementation details - Users don't need to know how features work internally
No marketing language - Avoid phrases like "powerful," "easy," "amazing," "intuitive"
No filler phrases - Avoid "simply," "just," "easily," "in order to"
No excessive caution - Don't add warnings for things that won't cause problems

Examples

Good:

To draw a rectangle, select the Rectangle tool and drag diagonally across the canvas.

Bad:

Simply click on the powerful Rectangle tool to easily create amazing rectangles! Just drag your mouse across the canvas.

Good:

Shapes in Doodle Mode are organized into layers by color.

Bad:

Under the hood, the doodle sort algorithm analyzes overlapping shapes and builds a dependency graph to determine optimal stacking order.

3. Content Types

3.1 Reference Documentation

Purpose: Explain what each feature/tool does and how to use it.

Structure:

Brief description (1-2 sentences)
How to access/activate
How to use (step-by-step if needed)
Options/settings (if any)
Tips (optional, 1-2 practical tips)

Examples: Tool references, keyboard shortcuts, menu descriptions

3.2 Task Guides (How-To)

Purpose: Walk users through accomplishing specific goals.

Structure:

What you'll accomplish (1 sentence)
Prerequisites (if any)
Steps (numbered, imperative)
Result (what success looks like)
Next steps (optional, related tasks)

Examples: "Creating Your First Design," "Exporting for 3D Printing," "Using Photo Guide to Trace an Image"

3.3 Concept Explanations

Purpose: Help users understand key concepts that affect how they work.

Structure:

What it is (definition)
Why it matters (practical impact)
How to use it (brief)
Related features (links)

Examples: "Understanding Shapes vs. Spaces," "How Doodle Mode Layers Work"

3.4 Quick Reference

Purpose: Provide at-a-glance information for experienced users.

Structure:

Tables, lists, or cards
Minimal prose
Scannable format

Examples: Keyboard shortcuts table, tool icon reference

4. Documentation Structure

Organization Hierarchy

/docs
├── Getting Started/
│   ├── index.md (Overview)
│   ├── your-first-design.md
│   ├── interface-tour.md
│   └── saving-and-exporting.md
│
├── Drawing Tools/
│   ├── index.md (Overview)
│   ├── pen-tools.md
│   ├── shape-tools.md
│   ├── text-tool.md
│   ├── eraser-tool.md
│   └── photo-guide.md
│
├── 3D Tools/
│   ├── index.md (Overview)
│   ├── height-and-extrusion.md
│   ├── sculpt-and-twist.md
│   ├── 3d-primitives.md
│   ├── boolean-operations.md
│   └── spaces-and-planes.md
│
├── Modes/
│   ├── index.md (Overview)
│   ├── doodle-mode.md
│   ├── code-mode.md
│   └── maker-mode.md
│
├── Working with Designs/
│   ├── index.md (Overview)
│   ├── saving-designs.md
│   ├── importing-files.md
│   ├── exporting-for-printing.md
│   └── sharing-designs.md
│
├── Design Library/
│   ├── index.md (Overview)
│   ├── browsing-designs.md
│   ├── publishing-designs.md
│   └── user-profiles.md
│
├── Guides/
│   ├── index.md (Overview)
│   ├── tracing-images.md
│   ├── creating-cookie-cutters.md
│   ├── multi-color-prints.md
│   └── using-code-mode.md
│
└── Reference/
    ├── keyboard-shortcuts.md
    ├── file-formats.md
    └── troubleshooting.md

Frontmatter Requirements

Every documentation file must include:

---
title: "Documentation Framework"
description: "Internal guidelines for writing CADit user documentation. Not shown in public docs."
order: 999
---

Documentation Ordering

The order field in frontmatter controls how documentation appears in the sidebar navigation. Documentation is sorted by:

Primary: order field (numeric, ascending)
Secondary: title (alphabetical, if order values match)

Files without an order field default to 999 and appear last.

Section Order (Top-Level)

Assign section order values to control sidebar navigation order. Use these ranges:

Order	Section	Purpose
0	cadit-overview.md	Landing page, introduction
10	getting-started/	First-time user orientation
20	drawing-tools/	Core 2D drawing features
30	3d-tools/	Core 3D manipulation features
40	modes/	Special interaction modes
50	working-with-designs/	Save, import, export
60	design-library/	Library and sharing
70	object-makers/	Parametric objects
80	guides/	Task-focused tutorials
90	reference/	Keyboard shortcuts, troubleshooting

Using increments of 10 allows inserting new sections without renumbering existing ones.

Section Index Files

The index.md file in each section folder serves two purposes:

It becomes the section header in the sidebar navigation
Its order value determines where the section appears relative to other sections

Important: The index.md order value should match the section's top-level order (10, 20, 30...), not start at 0.

Within-Section Order

Other files inside each section folder use their own ordering:

Order	File	Purpose
1-9	Primary content	Core tools/features in logical sequence
10+	Secondary content	Less common features, advanced topics

Rules:

Section index.md uses the section-level order (10, 20, 30...)
Other files in the section use 1, 2, 3... for internal ordering
Use sequential numbers (1, 2, 3...) not gaps (1, 5, 10...)
Order by user workflow or frequency of use, not alphabetically
Avoid duplicate order values within a section

Example

getting-started/           Section order: 10
├── index.md          order: 10  (Section header, determines section position)
├── interface-tour.md order: 1   (First thing to learn)
├── your-first-design.md order: 2   (Then create something)
└── saving-and-exporting.md order: 3   (Finally, save it)

Naming Conventions

Use lowercase with hyphens: your-first-design.md
Keep names short but descriptive
Match the page title where practical

5. Writing Guidelines

Formatting

Headings

Use H2 (##) for major sections within a page
Use H3 (###) for subsections
Keep headings concise and descriptive
Use sentence case: "Creating your first shape" not "Creating Your First Shape"

Lists

Use numbered lists for sequential steps
Use bullet lists for non-sequential items
Keep list items parallel in structure

Images and Media

Place images in /cadit-next/public/docs/ or /cadit-next/public/user-docs/
Use descriptive alt text
Reference images with relative paths: ![Alt text](/user-docs/screenshots/filename.png)
Prefer screenshots that show context (tool + result)
Videos for complex interactions (drawing, multi-step processes)

Tables

Use tables for reference data (shortcuts, parameters)
Include headers
Keep cells concise

Links

Link to related documentation where helpful
Use relative links: [Doodle Mode](../modes/doodle-mode)
Don't over-link; one or two per section is usually sufficient

Instructions

Step Format

1. Select the Rectangle tool from the toolbar
2. Click and drag diagonally on the canvas
3. Release to complete the shape

Key Principles:

Start each step with an action verb
One action per step
Include the result when it's not obvious
Use consistent terminology

Terminology

Use consistent terms throughout documentation:

Use	Don't Use
canvas	drawing area, workspace
shape	object (in 2D context)
design	sketch, project, file
toolbar	menu bar, tool palette
3D panel / 2D panel	3D view, 2D view
click	tap (unless specifically touch)
select	choose, pick
drag	click and drag, draw

6. Screenshots and Visual Assets

Screenshot Guidelines

Content

Show the relevant UI area, not the entire screen
Include enough context to orient the user
Highlight the relevant element if it's not obvious
Use consistent window/viewport sizes

Technical Specs

Format: PNG for screenshots, MP4/WebM for videos
Resolution: 2x for retina displays
Max width: 800px for full-width images
Crop whitespace

Naming

Descriptive names: rectangle-tool-selected.png
Group by feature: doodle-mode-layer-panel.png
Use hyphens, lowercase

Screenshot Todo Tracking

Screenshots and videos should be tracked separately from documentation. Create entries in the playbook todo list (see: /docs/core/Architecture/automated-documentation.md) specifying: