Skip to content

README Standardization Guide

This guide provides instructions and examples for implementing the standardized README structure across all projects in the monorepo. Following these guidelines will ensure consistency and better documentation for developers of all skill levels.

Contents

Implementation Process

To standardize READMEs across the monorepo:

  1. Use the README Template as your starting point
  2. Adapt the template to your specific project type (service, library, etc.)
  3. Fill in all required sections with project-specific information
  4. Add any additional sections that are relevant to your project
  5. Validate against the README Checklist

What Makes a Good README

A good project README should:

  • Be concise yet complete - Provide enough information without overwhelming the reader
  • Be beginner-friendly - Use clear language and explain concepts for newcomers
  • Include copy-pastable commands - Make it easy to get started with ready-to-use commands
  • Explain prerequisites clearly - Specify exact version requirements
  • Provide troubleshooting help - Include solutions for common issues
  • Show the project structure - Help developers navigate the codebase
  • Link to related resources - Connect to other relevant documentation

Template Usage

For Services (apps/*)

For services in the apps/ directory, use the full template and ensure you include:

  • API endpoints documentation
  • Environment variable requirements
  • Deployment information
  • Health and monitoring details
  • Integration points with other services

For Libraries (libs/*)

For libraries in the libs/ directory, focus on:

  • Installation and import instructions
  • API documentation with examples
  • Export structure
  • Usage examples for common scenarios
  • Dependency information

Section-by-Section Guidelines

Overview

  • Keep it concise (2-3 sentences) but informative
  • Include the project's primary purpose and role in the system
  • Add a "Beginner Tip" with a simpler explanation for newcomers

Example:

## Overview

The Datastream service ingests and processes real-time market data from external providers and makes it available to other services through Redis. It's a critical infrastructure component that ensures all trading services have access to up-to-date pricing information.

> 💡 **Beginner Tip**: This service acts like a bridge that takes price data from outside sources and makes it available to our trading services. Think of it as the "price feed" for our exchange.

Features

  • List 3-5 key capabilities, not implementation details
  • Add a brief explanation for each feature
  • Use active verbs (e.g., "Processes", "Manages", "Provides")

Example:

## Features

- **Real-time data processing** - Handles market updates within milliseconds
- **Automatic reconnection** - Maintains stable connections to data providers
- **Configurable data sources** - Easily switch between or add new data providers
- **Health monitoring** - Provides status endpoints and metrics for observability

Technical Specifications

  • Be specific about versions and requirements
  • Organize dependencies by category
  • Include internal library dependencies with links

Example:

### Core Technology Stack

- **Runtime**: Node.js >= 22.0.0
- **Primary Frameworks**: Express 4.21.2, WebSocket 8.13.0
- **Build System**: NX with ESBuild
- **Service Type**: Streaming Service
- **Version**: 0.1.0

### Dependencies

- **Core**:
  - ws - WebSocket client and server for real-time data streaming
  - redis - In-memory data store client for publishing market data
- **Testing**:
  - Jest - Testing framework for unit and integration tests
  - Redis Mock - Redis mocking for integration tests
- **Internal Libraries**:
  - [commons-ts](/libs/commons-ts) - Shared utilities and types
  - [connections-ts](/libs/connections-ts) - Database and external service connections

Getting Started

  • Include exact version requirements
  • Provide copy-pastable commands
  • Explain environment variables

Example:

### Prerequisites

- Node.js 22.x
- Yarn 4.x
- Redis server 7.x

### Environment Setup

```bash
# Copy and configure environment variables
cp .env.example .env
# Edit .env with appropriate values
```

Required environment variables:

CHAINLINK_API_KEY=your_api_key # API key for Chainlink data access
REDIS_HOST=localhost # Redis server hostname
REDIS_PORT=6379 # Redis server port

### Architecture

- Include visual diagrams where possible
- Explain key components and their interactions
- Show the directory structure with purpose explanations

**Example:**
```markdown
### Core Components

1. **WebSocket Client** (src/chainlink/indexPrice.ts)
   - Establishes and maintains WebSocket connections to Chainlink
   - Handles authentication, reconnection, and error recovery
   - Processes incoming market data messages

2. **Data Processor** (src/blockScholes/optionsMarketData.ts)
   - Transforms raw market data into standardized format
   - Validates data integrity and completeness
   - Handles special cases like expiration dates

Troubleshooting

  • Include common errors you've encountered during development
  • Provide clear step-by-step solutions
  • Add debugging tips for common scenarios

Example:

### Common Issues

| Issue                              | Possible Cause                                  | Solution                                                                                                                                         |
| ---------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Connection timeout to external API | API key expired or network issue                | 1. Verify API key is valid<br>2. Check network connectivity<br>3. Confirm the service URL is correct                                             |
| "Redis connection refused" error   | Redis server not running or wrong configuration | 1. Ensure Redis is running (`redis-cli ping`)<br>2. Check REDIS_HOST and REDIS_PORT in .env<br>3. Verify network allows connection to Redis port |

Service-Specific Examples

API Service Example (OrderBook)

See OrderBook README Example for a complete example of a standardized README for an API service.

Data Service Example (DataStream)

See DataStream README Example for a complete example of a standardized README for a data processing service.

Library-Specific Examples

Utility Library Example (commons-ts)

See Commons-TS README Example for a complete example of a standardized README for a utility library.

Client Library Example (connections-ts)

See Connections-TS README Example for a complete example of a standardized README for a client library.

README Checklist

Use this checklist to validate your README before submitting:

  • [ ] Has a concise overview with beginner-friendly explanation
  • [ ] Lists key features with brief explanations
  • [ ] Includes exact version requirements for all prerequisites
  • [ ] Provides copy-pastable installation and setup commands
  • [ ] Documents all required environment variables with explanations
  • [ ] Includes architecture diagram or component descriptions
  • [ ] Documents API endpoints (for services) or exports (for libraries)
  • [ ] Provides usage examples with code snippets
  • [ ] Includes troubleshooting section with common issues
  • [ ] Links to related projects and resources
  • [ ] Has been reviewed for technical accuracy
  • [ ] Uses consistent formatting and language style
  • [ ] Follows Markdown best practices
  • [ ] Is comprehensive yet concise