Repository navigation
Style Guide
This style guide ensures consistency, clarity, and maintainability across all ruv-FANN documentation. Following these standards improves readability and reduces maintenance overhead.
Every page must start with:
# Page Title
## Overview
Brief description of what this page covers and its purpose.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
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)- 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
| 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) |
- Spell out on first use: "Application Programming Interface (API)"
- Use sparingly in body text
- OK in code examples, headers, and tables
// 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()?;- 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)
<!-- Good -->
See the [Installation Guide](Installation-Guide.md) for setup instructions.
<!-- Avoid -->
See [here](Installation-Guide.md) for setup.<!-- 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).- 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
Use for sequential steps:
1. Install Rust toolchain
2. Clone the repository
3. Build the project
4. Run testsUse for features, options, or non-sequential items:
- High performance neural networks
- SIMD optimization
- WebAssembly support
- Cross-platform compatibilityUse for:
- Important concepts: neural network architecture
- UI elements: Click the Save button
- Warnings: Warning: This operation cannot be undone
Use for:
- Technical terms on first use: Configure the learning rate
- File names: Edit the config.toml file
- Emphasis: This is particularly important
Use for:
- Function names:
build_network() - Variable names:
learning_rate - File paths:
/src/lib.rs - Command-line tools:
cargo build
| Component | Performance | Memory Usage | Platform Support |
|-----------|-------------|--------------|------------------|
| ruv-FANN Core | 2-3x baseline | Standard | All platforms |
| Semantic Cartan | 2.8-4.4x | Optimized | Native + WASM |- Always include headers
- Align content logically
- Use consistent terminology
- Include units for measurements
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.34sJavaScript:
// 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);
}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 matricesAll code examples must be:
- Tested: Run successfully with current versions
- Complete: Include necessary imports and setup
- Realistic: Use meaningful examples, not trivial cases
Include version requirements:
**Requirements:**
- Rust 1.70 or later
- Node.js 18.0 or later
- CUDA 12.0+ (for GPU features)- Review quarterly for accuracy
- Update version requirements as needed
- Verify all links work correctly
- Test code examples with latest versions
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
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
-
Inconsistent Code Formatting
- Problem: Mixed indentation styles
- Solution: Use 4 spaces for Rust, 2 for JS/JSON
-
Overly Long Code Examples
- Problem: 100+ line examples in docs
- Solution: Break into focused, smaller examples
-
Missing Context
- Problem: Code without imports or setup
- Solution: Include complete, runnable examples
-
Vague Performance Claims
- Problem: "Much faster" without specifics
- Solution: Provide exact measurements and context
-
Broken Cross-References
- Problem: Links to renamed or moved pages
- Solution: Regular link checking and updates
# 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 Reference: Component Name
## Overview
Brief description of the component and its role.
## Installation
```bash
cargo add component-nameuse component_name::*;
// Simple exampleDescription of what the function does.
Parameters:
-
param: Description of parameter
Returns:
- Description of return value
Example:
let result = function_name(value);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.