Style Guide - ruvnet/ruv-FANN GitHub Wiki

Documentation Style Guide

Overview

This style guide ensures consistency, clarity, and maintainability across all ruv-FANN documentation. Following these standards improves readability and reduces maintenance overhead.

📋 Document Structure Standards

1. Page Headers

Every page must start with:

# Page Title

## Overview
Brief description of what this page covers and its purpose.

2. Required Sections

For Technical Documentation:

  • Overview
  • Installation/Setup (if applicable)
  • Usage Examples
  • API Reference (if applicable)
  • Troubleshooting (if applicable)
  • References

For Conceptual Documentation:

  • Overview
  • Key Concepts
  • Implementation Details
  • Examples
  • Best Practices
  • Further Reading

3. Table of Contents

For pages longer than 200 lines, include a TOC after the overview:

## Table of Contents
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Advanced Features](#advanced-features)

🖊️ Writing Style Standards

1. Voice and Tone

  • Active voice: Use "Configure the network" instead of "The network should be configured"
  • Present tense: Use "The system processes" instead of "The system will process"
  • Direct and concise: Avoid unnecessary words and complex sentences
  • Technical precision: Use exact technical terms consistently

2. Language Guidelines

Terminology Consistency

Preferred Avoid
ruv-FANN RUV-FANN, Ruv-Fann, ruv_fann
Neural network neural net, NN
WebAssembly WASM (in text), Web Assembly
Command-line interface CLI (in text), command line
Semantic Cartan Matrix semantic cartan matrix, SCM
Configuration config (in formal text)

Abbreviations

  • Spell out on first use: "Application Programming Interface (API)"
  • Use sparingly in body text
  • OK in code examples, headers, and tables

3. Code Examples Standards

Code Block Format

// Always include language identifier
// Add comments for complex operations
use ruv_fann::prelude::*;

// Create a simple neural network
let mut net = NeuralNetwork::builder()
    .input_size(2)
    .hidden_layers(&[3])
    .output_size(1)
    .build()?;

Code Style Requirements

  • Always include language identifier (rust, bash, javascript, etc.)
  • Add explanatory comments for non-obvious operations
  • Use realistic examples, not just "foo" and "bar"
  • Include error handling where appropriate
  • Maximum line length: 80 characters
  • Consistent indentation (4 spaces for Rust, 2 for JavaScript/JSON)

4. Link Standards

Internal Links

<!-- Good -->
See the [Installation Guide](Installation-Guide.md) for setup instructions.

<!-- Avoid -->
See [here](Installation-Guide.md) for setup.

External Links

<!-- Good -->
Refer to the [Rust documentation](https://doc.rust-lang.org/) for details.

<!-- Include description -->
Download from [GitHub releases](https://github.com/ruvnet/ruv-FANN/releases).

🎨 Formatting Standards

1. Headers

  • Use sentence case: "Getting started" not "Getting Started"
  • Be descriptive: "Configure database connection" not "Configuration"
  • Use consistent hierarchy (H1 for title, H2 for main sections, H3 for subsections)
  • Avoid more than 4 header levels

2. Lists

Ordered Lists

Use for sequential steps:

1. Install Rust toolchain
2. Clone the repository
3. Build the project
4. Run tests

Unordered Lists

Use for features, options, or non-sequential items:

- High performance neural networks
- SIMD optimization
- WebAssembly support
- Cross-platform compatibility

3. Emphasis

Bold Text

Use for:

  • Important concepts: neural network architecture
  • UI elements: Click the Save button
  • Warnings: Warning: This operation cannot be undone

Italic Text

Use for:

  • Technical terms on first use: Configure the learning rate
  • File names: Edit the config.toml file
  • Emphasis: This is particularly important

Code Text

Use for:

  • Function names: build_network()
  • Variable names: learning_rate
  • File paths: /src/lib.rs
  • Command-line tools: cargo build

4. Tables

Standard Format

| Component | Performance | Memory Usage | Platform Support |
|-----------|-------------|--------------|------------------|
| ruv-FANN Core | 2-3x baseline | Standard | All platforms |
| Semantic Cartan | 2.8-4.4x | Optimized | Native + WASM |

Requirements

  • Always include headers
  • Align content logically
  • Use consistent terminology
  • Include units for measurements

5. Code Blocks

Language-Specific Formatting

Rust:

// Use descriptive variable names
// Include type annotations where helpful
use ruv_fann::prelude::*;

let network_config = NetworkConfig {
    input_size: 784,
    hidden_layers: vec![128, 64],
    output_size: 10,
    learning_rate: 0.01,
};

Bash:

# Include comments for complex commands
# Use long-form options for clarity
cargo build --release --features simd,gpu

# Show expected output when helpful
# Output: Finished release [optimized] target(s) in 2.34s

JavaScript:

// Use modern JavaScript syntax
// Include error handling
import init, { NeuralNetwork } from './pkg/ruv_fann.js';

try {
    await init();
    const net = new NeuralNetwork(784, [128, 64], 10);
    console.log('Network initialized successfully');
} catch (error) {
    console.error('Failed to initialize:', error);
}

📊 Technical Content Standards

1. Performance Claims

All performance claims must be:

  • Specific: "2.8x faster" not "much faster"
  • Contextual: Include baseline and test conditions
  • Verifiable: Reference benchmarks or provide reproduction steps

Example:

Performance on Intel i9-13900K with AVX2:
- Matrix multiplication: 4.4x speedup over scalar implementation
- Training throughput: 2.8x improvement on MNIST dataset
- Memory usage: 35% reduction compared to dense matrices

2. Code Accuracy

All code examples must be:

  • Tested: Run successfully with current versions
  • Complete: Include necessary imports and setup
  • Realistic: Use meaningful examples, not trivial cases

3. Version Information

Include version requirements:

**Requirements:**
- Rust 1.70 or later
- Node.js 18.0 or later
- CUDA 12.0+ (for GPU features)

🔧 Maintenance Standards

1. Regular Updates

  • Review quarterly for accuracy
  • Update version requirements as needed
  • Verify all links work correctly
  • Test code examples with latest versions

2. Consistency Checks

Run these checks before publishing:

  • All headers use consistent capitalization
  • Code blocks have language identifiers
  • External links include descriptions
  • Performance claims are specific and verifiable
  • Terminology follows the approved list

3. Quality Metrics

Target metrics for documentation quality:

  • Readability: Flesch Reading Ease score > 60
  • Accuracy: All code examples tested
  • Completeness: Cover all major use cases
  • Maintenance: Last updated within 6 months

🚨 Issues to Avoid

Common Problems Found in Review

  1. Inconsistent Code Formatting

    • Problem: Mixed indentation styles
    • Solution: Use 4 spaces for Rust, 2 for JS/JSON

  2. Overly Long Code Examples

    • Problem: 100+ line examples in docs
    • Solution: Break into focused, smaller examples

  3. Missing Context

    • Problem: Code without imports or setup
    • Solution: Include complete, runnable examples

  4. Vague Performance Claims

    • Problem: "Much faster" without specifics
    • Solution: Provide exact measurements and context

  5. Broken Cross-References

    • Problem: Links to renamed or moved pages
    • Solution: Regular link checking and updates

📝 Templates

New Page Template

# Page Title

## Overview
Brief description of what this page covers and its purpose.

## Key Concepts
- Concept 1: Description
- Concept 2: Description

## Getting Started
Basic usage example with minimal setup.

## Examples
Practical examples with complete code.

## Troubleshooting
Common issues and solutions.

## References
- [Related Documentation](link)
- [External Resources](link)

API Documentation Template

# API Reference: Component Name

## Overview
Brief description of the component and its role.

## Installation
```bash
cargo add component-name

Basic Usage

use component_name::*;

// Simple example

API Reference

Functions

function_name(param: Type) -> ReturnType

Description of what the function does.

Parameters:

  • param: Description of parameter

Returns:

  • Description of return value

Example:

let result = function_name(value);

Error Handling

Common errors and how to handle them.


## Review Checklist

Before publishing any documentation:

### Content Review
- [ ] Purpose and scope clearly stated
- [ ] All code examples tested and working
- [ ] Performance claims verified
- [ ] Links checked and working
- [ ] Version requirements specified

### Style Review
- [ ] Headers use sentence case
- [ ] Consistent terminology throughout
- [ ] Code blocks have language identifiers
- [ ] Tables are properly formatted
- [ ] Lists use appropriate numbering/bullets

### Technical Review
- [ ] Code examples are complete and realistic
- [ ] Error handling included where appropriate
- [ ] Security considerations mentioned if applicable
- [ ] Cross-platform compatibility noted
- [ ] Dependencies clearly specified

This style guide ensures all ruv-FANN documentation maintains professional quality while being accessible to developers at all levels.