Skip to content

Documentation

Jump to bottom
github-actions[bot] edited this page Oct 16, 2025 · 1 revision

Documentation Contributing Guide

Thank you for helping improve the painlessMesh documentation! This guide will help you contribute effectively.

Documentation Structure

The documentation is organized into these main directories:

docs/
├── README.md                    # Documentation index
├── getting-started/             # Installation and quickstart guides
├── tutorials/                   # Step-by-step tutorials
├── api/                         # API reference documentation
├── architecture/                # System design and architecture docs
├── alteriom/                    # Alteriom-specific extensions
├── troubleshooting/             # Common issues and debugging
├── development/                 # Development and testing docs
├── releases/                    # Release notes and summaries
├── improvements/                # Feature proposals and enhancements
└── archive/                     # Historical/obsolete documentation

Documentation Standards

Markdown Style

We follow the Markdown Style Guide with these specific conventions:

Headers:

  • Use ATX-style headers (# syntax)
  • Add blank lines before and after headers
  • Use sentence case (capitalize first word only)
# Main heading

## Section heading

Content goes here.

### Subsection heading

Lists:

  • Add blank lines before and after lists
  • Use - for unordered lists
  • Use 1. for ordered lists
  • Indent nested lists by 2 spaces
Here's a list:

- First item
- Second item
  - Nested item
  - Another nested
- Third item

Back to content.

Code Blocks:

  • Add blank lines before and after code blocks
  • Always specify language for syntax highlighting
  • Use cpp for Arduino/C++ code
  • Use bash for shell commands
  • Use ini for PlatformIO config
Example code:

```cpp
#include "painlessMesh.h"

painlessMesh mesh;
void setup() {
  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler);
}

Back to content.


**Links:**
- Use relative paths for internal documentation links
- Use descriptive link text (not "click here")
- Verify links work before committing

```markdown
Good: See the [debugging guide](../troubleshooting/debugging.md) for details.
Bad: For more info, click [here](../troubleshooting/debugging.md).

File Naming

  • Use lowercase with hyphens: my-document.md
  • Be descriptive: mqtt-bridge-setup.md not mqtt.md
  • Use consistent prefixes for related docs

Content Guidelines

Be Clear and Concise:

  • Write in active voice
  • Use short sentences and paragraphs
  • Define acronyms on first use
  • Include examples for complex topics

Be Accurate:

  • Test all code examples before documenting
  • Verify API references against source code
  • Update version numbers and compatibility info
  • Link to related documentation

Be Helpful:

  • Anticipate user questions
  • Provide troubleshooting tips
  • Include "common mistakes" sections
  • Add "See Also" references

Types of Documentation

1. Getting Started Guides

Purpose: Help new users get up and running quickly

Should Include:

  • Prerequisites
  • Installation steps
  • First example
  • Next steps / what to read next

Example Structure:

# Quick Start Guide

## Prerequisites
- Hardware requirements
- Software requirements

## Installation
Step-by-step installation

## Your First Mesh
Simple working example with explanation

## Next Steps
- Link to tutorials
- Link to API reference

2. Tutorials

Purpose: Teach specific skills through hands-on practice

Should Include:

  • Learning objectives
  • Required materials/setup
  • Step-by-step instructions
  • Complete working code
  • Explanation of concepts
  • Troubleshooting section

Example Structure:

# Tutorial: Building a Sensor Network

**What you'll learn:**
- How to use SensorPackage
- Broadcasting sensor data
- ...

**What you'll need:**
- 2+ ESP32 devices
- DHT22 sensor
- ...

## Step 1: Setup
...

## Step 2: Code
...

## Troubleshooting
...

3. API Documentation

Purpose: Comprehensive reference for all classes and methods

Should Include:

  • Class/function signature
  • Parameters with types
  • Return values
  • Description
  • Usage examples
  • Related functions

Example Structure:

### mesh.sendBroadcast()

Sends a message to all nodes in the mesh.

**Signature:**
```cpp
bool sendBroadcast(String& msg);

Parameters:

  • msg (String&): Message to broadcast (JSON recommended)

Returns:

  • true if message queued successfully
  • false if queue full or error

Example:

String msg = "{\"type\":\"sensor\",\"value\":42}";
if (mesh.sendBroadcast(msg)) {
  Serial.println("Message sent");
}

See Also:

  • sendSingle() - Send to specific node
  • onReceive() - Receive messages

### 4. Architecture Documentation

**Purpose:** Explain system design and internals

**Should Include:**
- High-level overview
- Component diagrams
- Data flow diagrams
- Design decisions and rationale
- Performance characteristics

### 5. Troubleshooting Guides

**Purpose:** Help users solve problems

**Should Include:**
- Symptom description
- Diagnostic steps
- Common causes
- Solutions
- Prevention tips

**Example Structure:**
```markdown
## Problem: Nodes Not Connecting

**Symptoms:**
- Nodes don't appear in node list
- onNewConnection never fires

**Diagnostic Steps:**
1. Enable debug: `mesh.setDebugMsgTypes(ERROR | CONNECTION)`
2. Check serial output for errors
3. ...

**Common Causes:**
- Mismatched MESH_PREFIX
- Different MESH_PORT
- ...

**Solutions:**
- Verify all nodes use same credentials
- ...

**Prevention:**
- Use configuration file for mesh settings
- ...

Contributing Process

1. Before You Start

  • Check existing issues: Someone may already be working on it
  • Discuss major changes: Open an issue for significant additions
  • Review existing docs: Maintain consistency with current documentation

2. Making Changes

For Minor Edits (typos, clarifications):

  1. Edit directly on GitHub
  2. Submit pull request
  3. Describe what you fixed

For Major Additions:

  1. Fork the repository
  2. Create a branch: git checkout -b docs/mqtt-bridge-guide
  3. Make your changes
  4. Test locally (see below)
  5. Commit with descriptive message
  6. Push and create pull request

3. Testing Your Changes

Check Markdown Formatting:

# Install markdownlint
npm install -g markdownlint-cli

# Check your files
markdownlint docs/**/*.md

# Auto-fix what's possible
markdownlint --fix docs/**/*.md

Preview Locally:

# Option 1: VS Code with Markdown Preview
# Just open .md file and press Ctrl+Shift+V

# Option 2: Serve docs locally
cd docs
python -m http.server 8000
# Open http://localhost:8000

Verify Links:

# Check for broken links
grep -r "](.*\.md)" docs/ | # Find all markdown links
while read line; do
  # Extract and check each link exists
  # (manual verification recommended)
done

4. Pull Request Guidelines

PR Title:

  • docs: add MQTT bridge tutorial
  • docs: fix broken links in API reference
  • docs: update installation guide for v1.7.0

PR Description:

## What
Brief description of changes

## Why
Why this documentation is needed

## Changes
- Added new tutorial for X
- Updated API reference for Y
- Fixed broken links in Z

## Checklist
- [ ] Markdown formatting checked
- [ ] Code examples tested
- [ ] Links verified
- [ ] Added to appropriate index/README

Documentation Maintenance

Keeping Docs Current

Version Updates:

  • Update version numbers in examples
  • Mark deprecated features
  • Add "New in v1.X" callouts

Code Examples:

  • Test examples with each release
  • Update for API changes
  • Verify dependencies

Link Checking:

  • Periodically verify internal links
  • Check external links still valid
  • Update or remove dead links

Documentation Reviews

When reviewing documentation PRs, check:

  • Accuracy: Information is correct and up-to-date
  • Clarity: Easy to understand for target audience
  • Completeness: Covers the topic adequately
  • Examples: Code examples work and are helpful
  • Style: Follows our markdown conventions
  • Links: All links work correctly
  • Grammar: No typos or grammar errors
  • Navigation: Added to appropriate index/README

Common Documentation Tasks

Adding a New Tutorial

  1. Create file in docs/tutorials/
  2. Follow tutorial structure (see above)
  3. Add entry to docs/README.md
  4. Add entry to docs/tutorials/README.md (if exists)
  5. Link from related documents

Updating API Reference

  1. Check source code for changes
  2. Update method signatures
  3. Update parameter descriptions
  4. Add/update examples
  5. Mark deprecated methods
  6. Update version compatibility info

Fixing Broken Links

  1. Find broken links: grep -r "](.*\.md)" docs/
  2. Verify which files moved/renamed
  3. Update all references
  4. Check git history if uncertain
  5. Test links in preview

Adding Code Examples

Best Practices:

  • Keep examples minimal and focused
  • Include necessary includes
  • Comment complex sections
  • Test before documenting
  • Show both setup and usage
  • Include error handling

Example Template:

/**
 * Example: Sensor Data Broadcasting
 * 
 * Demonstrates how to broadcast sensor readings
 * using the Alteriom SensorPackage.
 * 
 * Hardware: ESP32 + DHT22 sensor
 * Libraries: painlessMesh, DHT sensor library
 */

#include "painlessMesh.h"
#include "examples/alteriom/alteriom_sensor_package.hpp"
#include "DHT.h"

#define MESH_PREFIX     "SensorMesh"
#define MESH_PASSWORD   "password123"
#define MESH_PORT       5555
#define DHT_PIN         4
#define DHT_TYPE        DHT22

Scheduler userScheduler;
painlessMesh mesh;
DHT dht(DHT_PIN, DHT_TYPE);

void sendSensorData() {
  // Read sensor
  float temp = dht.readTemperature();
  float humidity = dht.readHumidity();
  
  // Check for errors
  if (isnan(temp) || isnan(humidity)) {
    Serial.println("Failed to read from DHT sensor");
    return;
  }
  
  // Create package
  alteriom::SensorPackage pkg;
  pkg.sensorId = mesh.getNodeId();
  pkg.temperature = temp;
  pkg.humidity = humidity;
  pkg.timestamp = mesh.getNodeTime();
  
  // Convert to JSON and broadcast
  auto var = painlessmesh::protocol::Variant(&pkg);
  String msg = var.to<String>();
  
  if (mesh.sendBroadcast(msg)) {
    Serial.printf("Sent: T=%.1f°C H=%.1f%%\n", temp, humidity);
  }
}

Task sensorTask(TASK_MINUTE, TASK_FOREVER, &sendSensorData);

void setup() {
  Serial.begin(115200);
  
  // Initialize sensor
  dht.begin();
  
  // Initialize mesh
  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
  
  // Add task
  userScheduler.addTask(sensorTask);
  sensorTask.enable();
}

void loop() {
  mesh.update();
}

Style Cheatsheet

Quick Reference

# H1 - Main page title (one per page)

## H2 - Major sections

### H3 - Subsections

**Bold** for emphasis, `code` for technical terms

- Unordered lists
  - Nested items
1. Ordered lists
2. For sequential steps

```cpp
// Code blocks with language
void example() {
  // Code here
}

Blockquotes for important notes

Tables Are Supported
Use For Structured data

Link text


## Questions?

- **General questions:** Open a [discussion](https://github.com/Alteriom/painlessMesh/discussions)
- **Found an error:** Open an [issue](https://github.com/Alteriom/painlessMesh/issues)
- **Want to help:** Check [good first issues](https://github.com/Alteriom/painlessMesh/labels/good%20first%20issue)

## See Also

- [Contributing Guidelines](../../CONTRIBUTING.md) - General contribution guide
- [Code Style Guide](contributing.md) - Code contribution standards
- [Release Guide](../../RELEASE_GUIDE.md) - Release process documentation

Clone this wiki locally