Technical Documentation

Technical Documentation

This skill provides patterns, templates, and best practices for creating clear, maintainable technical documentation for Node-RED projects and related software.

When to Use This Skill

• Writing or updating README files
• Creating usage guides and how-tos
• Documenting architecture and design decisions
• Writing migration guides for breaking changes
• Creating troubleshooting documentation
• Building Node-RED flow examples
• Managing changelogs and release notes
• Creating API documentation

Documentation Types

README Files

A README is the first documentation users encounter. Structure for maximum clarity:

# Project Name

One-line description of what this project does.

## Features

- Feature 1: Brief description
- Feature 2: Brief description

## Installation

\`\`\`bash
npm install @scope/package-name
\`\`\`

## Quick Start

Minimal example to get started immediately.

## Configuration

Document all configuration options with defaults.

## Usage Examples

Show common use cases with code examples.

## API Reference

Link to detailed API docs or include inline.

## Troubleshooting

Common issues and solutions.

## Contributing

How to contribute to the project.

## License

License type and link to LICENSE file.

How-To Guides

Task-oriented documentation that guides users through specific goals:

# How to [Accomplish Task]

## Overview

Brief description of what this guide covers and prerequisites.

## Prerequisites

- Required software/knowledge
- Configuration needed

## Steps

### Step 1: [Action]

Explanation of what this step accomplishes.

\`\`\`bash
# Commands or code
\`\`\`

Expected output or result.

### Step 2: [Action]

Continue with numbered steps...

## Verification

How to confirm the task was completed successfully.

## Next Steps

Related guides or advanced topics.

Architecture Documentation

Document system design for maintainers and contributors:

# Architecture Overview

## System Context

High-level view of where this project fits in the larger ecosystem.

## Components

### Component Name

- **Purpose**: What it does
- **Responsibilities**: What it's responsible for
- **Dependencies**: What it depends on
- **Interface**: How other components interact with it

## Data Flow

Describe how data moves through the system.

## Key Design Decisions

### Decision 1: [Title]

- **Context**: What situation led to this decision
- **Decision**: What was decided
- **Rationale**: Why this choice was made
- **Consequences**: Trade-offs and implications

## Deployment

How the system is deployed and operated.

Migration Guides

Help users upgrade between versions:

# Migration Guide: v1.x to v2.x

## Overview

Summary of breaking changes and new features.

## Breaking Changes

### Change 1: [Description]

**Before (v1.x):**
\`\`\`javascript
// Old way
\`\`\`

**After (v2.x):**
\`\`\`javascript
// New way
\`\`\`

**Migration steps:**
1. Step one
2. Step two

### Change 2: [Description]

Continue for each breaking change...

## Deprecated Features

Features that still work but will be removed in future versions.

## New Features

Optional improvements users can adopt.

## Checklist

- [ ] Update dependency version
- [ ] Migrate breaking change 1
- [ ] Migrate breaking change 2
- [ ] Test functionality
- [ ] Update configuration

Troubleshooting Documentation

Help users solve problems independently:

# Troubleshooting

## Common Issues

### Issue: [Error Message or Symptom]

**Symptoms:**
- What the user observes

**Cause:**
Why this happens

**Solution:**
\`\`\`bash
# Commands to fix
\`\`\`

Or step-by-step instructions.

### Issue: [Another Problem]

Continue pattern...

## Diagnostic Commands

Useful commands for debugging:

\`\`\`bash
# Check version
node -v
npm list @scope/package

# View logs
tail -f ~/.node-red/node-red.log

# Test connectivity
curl -v http://localhost:1880
\`\`\`

## Getting Help

- GitHub Issues: link
- Community Forum: link
- Stack Overflow tag: tag-name

Node-RED Flow Examples

Example Flow Structure

Create example flows in the examples/ directory:

examples/
├── basic-usage.json
├── advanced-configuration.json
├── error-handling.json
└── README.md

Example Flow JSON Format

[
    {
        "id": "example-flow-tab",
        "type": "tab",
        "label": "Example: Basic Usage",
        "disabled": false,
        "info": "This flow demonstrates basic usage of the API Gateway node.\n\n## Prerequisites\n- Configure the server connection\n- API endpoint must be accessible\n\n## How it works\n1. Inject node triggers the request\n2. API Gateway node calls the endpoint\n3. Debug node shows the response"
    },
    {
        "id": "inject-node",
        "type": "inject",
        "z": "example-flow-tab",
        "name": "Trigger Request",
        "props": [
            {
                "p": "payload"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "{}",
        "payloadType": "json",
        "x": 150,
        "y": 100,
        "wires": [["api-gateway-node"]]
    },
    {
        "id": "api-gateway-node",
        "type": "api-gateway",
        "z": "example-flow-tab",
        "name": "Call API",
        "server": "",
        "endpoint": "/api/example",
        "method": "GET",
        "x": 350,
        "y": 100,
        "wires": [["debug-node"]]
    },
    {
        "id": "debug-node",
        "type": "debug",
        "z": "example-flow-tab",
        "name": "Show Response",
        "active": true,
        "tosidebar": true,
        "console": false,
        "tostatus": false,
        "complete": "payload",
        "targetType": "msg",
        "x": 550,
        "y": 100,
        "wires": []
    }
]

Example Flow Best Practices

1. Use descriptive tab info: Include prerequisites, how it works, and expected behavior
2. Name all nodes: Every node should have a meaningful name property
3. Logical positioning: Arrange nodes left-to-right, top-to-bottom
4. Include comments: Use comment nodes to explain complex sections
5. Avoid hardcoded values: Use environment variables or placeholders for sensitive data
6. Test before publishing: Import and run each example flow

Examples README

Create an examples/README.md:

# Example Flows

Import these example flows into Node-RED to learn how to use [Package Name].

## Available Examples

### basic-usage.json

Demonstrates the simplest way to use the node. Good starting point for new users.

**What it does:**
- Sends a simple GET request
- Displays the response

### advanced-configuration.json

Shows advanced features like authentication and error handling.

**What it does:**
- Configures authentication headers
- Handles errors gracefully
- Implements retry logic

### error-handling.json

Demonstrates proper error handling patterns.

**What it does:**
- Catches and logs errors
- Implements fallback behavior
- Shows status reporting

## How to Import

1. Open Node-RED editor
2. Menu (hamburger icon) > Import
3. Select file or paste JSON
4. Click Import
5. Deploy the flow

Changelog Management

Format: Keep a Changelog

Use Keep a Changelog format:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New features not yet released

### Changed
- Changes to existing functionality

### Deprecated
- Features that will be removed in future versions

### Removed
- Features removed in this release

### Fixed
- Bug fixes

### Security
- Security-related changes

## [1.2.0] - 2024-03-15

### Added
- Added retry configuration option (#45)
- Added support for custom headers

### Fixed
- Fixed timeout not being respected (#42)
- Fixed memory leak in connection pool

## [1.1.0] - 2024-02-01

### Added
- Initial feature set

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/repo/releases/tag/v1.1.0

Changelog Entry Guidelines

Added

New features and capabilities:

- Added retry configuration with exponential backoff (#123)
- Added `timeout` option to configuration node
- Added support for OAuth2 authentication

Changed

Modifications to existing features:

- Changed default timeout from 30s to 10s
- Updated minimum Node.js version to 18
- Improved error messages for connection failures

Deprecated

Features that will be removed:

- Deprecated `oldMethod()` in favor of `newMethod()`
- Deprecated legacy configuration format (will be removed in v3.0)

Removed

Features that have been removed:

- Removed support for Node.js 14
- Removed deprecated `legacyOption` configuration

Fixed

Bug fixes:

- Fixed race condition in request queue (#89)
- Fixed incorrect status display after reconnection
- Fixed memory leak when handling large responses

Security

Security patches:

- Fixed XSS vulnerability in error display
- Updated dependencies to patch CVE-2024-XXXXX
- Added input sanitization for user-provided URLs

Writing Good Changelog Entries

1. Start with a verb: Added, Changed, Fixed, Removed
2. Be specific: Mention what changed, not just that something changed
3. Reference issues: Include issue/PR numbers when applicable
4. User perspective: Describe impact on users, not implementation details
5. Keep it scannable: One line per change, grouped by type

Good:

- Fixed timeout not being applied to retry attempts (#42)

Bad:

- Bug fix
- Updated code
- Fixed issue reported by user

Breaking Changes

Document breaking changes prominently:

## [2.0.0] - 2024-04-01

### BREAKING CHANGES

- **Configuration format changed**: The `server` property now requires a URL instead of hostname/port

  Before:
  \`\`\`json
  { "hostname": "api.example.com", "port": 443 }
  \`\`\`

  After:
  \`\`\`json
  { "server": "https://api.example.com" }
  \`\`\`

  See [Migration Guide](./docs/migration-v2.md) for details.

- **Minimum Node.js version**: Now requires Node.js 18+

### Added
- New feature...

Writing Style Guidelines

General Principles

1. Be concise: Use short sentences and paragraphs
2. Use active voice: "Configure the node" not "The node should be configured"
3. Present tense: "This function returns" not "This function will return"
4. Second person for instructions: "You can configure..." or imperative "Configure..."
5. Consistent terminology: Pick terms and use them throughout

Code Examples

1. Complete and runnable: Examples should work when copied
2. Minimal: Show only what's necessary for the concept
3. Commented: Explain non-obvious parts
4. Realistic: Use believable values, not "foo" and "bar"

// Good: Realistic and complete
const config = {
    server: 'https://api.example.com',
    timeout: 5000,
    retries: 3
};

// Bad: Abstract and incomplete
const config = { foo: 'bar' };

Formatting

1. Headings: Use sentence case ("Getting started" not "Getting Started")
2. Lists: Use bullet points for unordered items, numbers for sequences
3. Code blocks: Always specify language for syntax highlighting
4. Links: Use descriptive text ("see the configuration guide" not "click here")

Reference Documentation

For detailed templates and style guidelines:

• references/style-guide.md - Comprehensive writing style reference
• assets/templates/ - Ready-to-use documentation templates

Common Documentation Mistakes

1. Assuming knowledge: Define terms, link to prerequisites
2. Outdated examples: Keep code examples synchronized with actual API
3. Missing context: Explain why, not just how
4. Wall of text: Break up with headings, lists, code blocks
5. No error documentation: Document what can go wrong
6. Ignoring edge cases: Cover unusual but valid scenarios
7. Inconsistent formatting: Use templates for consistency