luigi/
├── README.md                    # Main project overview and module directory
├── MODULE_SCHEMA.md             # Technical reference for module.json format
├── UNINSTALL_GUIDE.md          # Standalone operational guide
├── motion-detection/
│   ├── README.md               # Category overview (optional)
│   └── mario/
│       └── README.md           # Complete module documentation
├── iot/
│   └── ha-mqtt/
│       ├── README.md           # Complete module documentation
│       └── examples/
│           └── integration-guide.md  # Supplementary guide
└── system/
    └── management-api/
        ├── README.md           # User-facing module documentation
        └── docs/
            └── API.md          # Technical API reference (interface contract)

# Module Name

Brief one-line description of what the module does.

## Overview

Detailed description of the module's purpose, functionality, and use cases.

## Features

- Feature 1
- Feature 2
- Feature 3

## Hardware Requirements

List all required hardware components:
- Component name (with links to purchase if helpful)
- GPIO pins used (with BCM numbering)
- Wiring requirements
- Power requirements

Include wiring diagrams if complex (markdown table or image).

## Software Requirements

- Operating System
- Python version
- Required system packages
- Dependencies on other Luigi modules

## Installation

Step-by-step installation instructions:

### Automatic Installation (Recommended)

```bash
# Install from repository root
sudo ./setup.sh install category/module-name

# Example configuration
OPTION_1=value1
OPTION_2=value2

sudo systemctl start module-name
sudo systemctl stop module-name
sudo systemctl restart module-name

sudo systemctl status module-name
journalctl -u module-name -f

sudo ./setup.sh uninstall category/module-name

### Module README Best Practices

- **Complete and Self-Contained** - User should find everything they need
- **Hardware First** - Show wiring and GPIO before code
- **Command Examples** - Always show actual commands with output
- **Real-World Scenarios** - Include practical use cases
- **Troubleshooting** - Anticipate common problems
- **Keep Updated** - Update when features change
- **Screenshots** - Include for GUI components or complex output
- **Configuration Examples** - Show real config file snippets

## API Documentation (Special Case)

Backend API documentation serves as an **interface contract** between frontend and backend. It should be separate from the module README.

### When to Create Separate API Documentation

Create a separate API documentation file when:
- The module provides a REST API or web service
- Frontend and backend need a clear interface contract
- The API is complex with multiple endpoints
- API documentation would overwhelm the module README

### API Documentation Location

Place API documentation in a `docs/` subdirectory:

### API Documentation Structure

Follow the pattern in `system/management-api/docs/API.md`:

1. **Header with Version and Base URL**
2. **Table of Contents**
3. **Authentication** - How to authenticate
4. **Response Format** - Standard response structure
5. **Error Handling** - Error codes and formats
6. **Endpoint Groups** - Organized by functionality
   - Endpoint description
   - HTTP method and path
   - Request parameters
   - Response schema with TypeScript types
   - Example requests (curl, JavaScript)
   - Example responses

### API Documentation Best Practices

- **TypeScript Types** - Use TypeScript for response schemas
- **Complete Examples** - Show both curl and code examples
- **Error Cases** - Document all possible errors
- **Status Codes** - List all HTTP status codes used
- **Version It** - Include API version in documentation
- **Keep Synchronized** - Update when API changes
- **Interface Contract** - Treat as binding agreement between frontend/backend

## Category README (Optional)

Category-level READMEs (e.g., `motion-detection/README.md`) are optional and should only be created if:
- The category has multiple modules
- There's category-specific information to share
- You want to provide a category overview

If created, keep them brief:
- List modules in the category with links
- Explain the category purpose
- Link to individual module READMEs for details

## Technical Guides and Standalone Documents

For complex topics that don't fit in module READMEs, create standalone guides:

**Examples:**
- `UNINSTALL_GUIDE.md` - Complete uninstallation procedures
- `MODULE_SCHEMA.md` - Technical reference for module.json
- `MIGRATION_GUIDE.md` - Upgrading between versions
- `SECURITY.md` - Security policy and reporting

**Guidelines:**
- Place in repository root if project-wide
- Place in module directory if module-specific
- Use descriptive ALL_CAPS names
- Link from relevant READMEs
- Keep focused on single topic

## Documentation Hygiene

### Avoiding Documentation Sprawl

Documentation can accumulate over time, leading to confusion and maintenance burden. Follow these practices to keep documentation clean:

**Delete Obsolete Files:**
- Remove design documents after implementation is complete
- Delete implementation plans, summaries, and progress notes
- Remove fix/patch notes that have been integrated into main documentation
- Consolidate multiple similar documents into one authoritative source

**Types of Files to Remove:**
- `DESIGN_ANALYSIS.md`, `IMPLEMENTATION_PLAN.md` - These belong in issues/PRs, not main branch
- `FIX_SUMMARY.md`, `ENHANCEMENT_SUMMARY.md` - Integrate into troubleshooting or changelog
- `PR_DESCRIPTION.md` - This belongs in the actual PR, not the repository
- Multiple summary/update/guide files covering the same topic

**When to Keep Separate Documents:**
- Technical references that are rarely updated (e.g., `MODULE_SCHEMA.md`)
- Operational procedures that need emphasis (e.g., `UNINSTALL_GUIDE.md`)
- Integration guides for complex scenarios (in `examples/` subdirectory)
- Test documentation (in `tests/` subdirectory)

**Regular Cleanup:**
- Review markdown files quarterly
- Delete files that are outdated or have been superseded
- Consolidate redundant information
- Update main READMEs instead of creating new summary files

**Current Luigi Structure (14 markdown files):**

This is a healthy documentation structure. More files often indicate documentation sprawl that needs cleanup.

## Documentation Writing Style

### Tone and Voice

- **Clear and Direct** - Use simple language, avoid jargon
- **Action-Oriented** - Use imperative mood ("Install the module", not "The module can be installed")
- **Professional but Friendly** - Technical but approachable
- **Consistent Terminology** - Use same terms throughout

### Formatting Guidelines

**Code Blocks:**
- Always specify language: ```bash, ```python, ```json
- Include command prompts when showing terminal commands
- Show expected output when helpful
- Use comments to explain complex commands

**Links:**
- Use relative links within repository: `[Module](../module/)`
- Use descriptive link text: `[Mario module README](motion-detection/mario/)` not `[click here]`
- Verify links work after changes

**Lists:**
- Use `-` for unordered lists (not `*`)
- Use numbered lists for sequential steps
- Keep list items parallel in structure

**Headers:**
- Use ATX-style headers: `## Header` (not underline style)
- Don't skip header levels
- Use Title Case for main headers

**Emphasis:**
- Use **bold** for UI elements, filenames, important terms
- Use `code` for commands, code elements, paths
- Use *italics* sparingly for subtle emphasis

## Documentation Maintenance

### When to Update Documentation

Update documentation when:
- Adding new features or capabilities
- Changing configuration options
- Modifying installation procedures
- Adding dependencies
- Discovering common issues (add to troubleshooting)
- Improving examples based on user feedback

### Documentation Review Checklist

Before considering documentation complete:

- [ ] README exists in module directory
- [ ] Main project README updated if new module
- [ ] All code examples tested and work
- [ ] All commands verified on target platform
- [ ] Links checked and valid
- [ ] Configuration examples match actual config files
- [ ] GPIO pins documented with BCM numbering
- [ ] Dependencies listed completely
- [ ] Troubleshooting section includes common issues
- [ ] Installation and uninstallation procedures tested
- [ ] Integration with other modules documented if applicable
- [ ] API documentation updated if endpoints changed
- [ ] Spelling and grammar checked
- [ ] Formatting consistent with existing docs

## Examples and References

### Exemplar Module Documentation

**Best Examples in Luigi:**
- `motion-detection/mario/README.md` - Complete hardware module documentation
- `iot/ha-mqtt/README.md` - Complex integration module
- `system/management-api/README.md` - Web service module
- `system/management-api/docs/API.md` - Separate API documentation

Study these for patterns and structure.

### Common Documentation Patterns

See `documentation-patterns.md` for detailed examples of:
- Wiring diagrams in markdown
- Configuration documentation
- Troubleshooting sections
- Integration guides
- Installation procedures
- Service management

## Quick Reference

### New Module Checklist

When creating a new module:

1. Create module directory: `category/module-name/`
2. Create `README.md` using template above
3. Document all hardware requirements and GPIO pins
4. Document all configuration options
5. Include installation and usage examples
6. Add troubleshooting section
7. Update main project README module table
8. Test all documented commands
9. Add screenshots if module has GUI

### Updating Main README

When adding a module to the project:

1. Add row to "Current Modules" table
2. Include module name with link to README
3. Specify category
4. Write one-line description
5. Maintain alphabetical or logical ordering
6. Update module counts if mentioned elsewhere

### Quick Tips

- **Start with examples** - Show before explaining
- **Test everything** - Run every command you document
- **Be specific** - Include actual paths, pins, values
- **Link liberally** - Help users navigate documentation
- **Update proactively** - Don't let docs drift from code
- **Think user-first** - What would someone new need to know?

## See Also

- **Module Design Skill** (`.github/skills/module-design/`) - Designing modules before implementation
- **Shell Scripting Skill** (`.github/skills/shell-scripting/`) - Writing setup scripts
- **Main Project README** (`/README.md`) - Documentation structure example
- **Module README Template** (`documentation-patterns.md`) - Detailed examples