Article 8: Documentation Best Practices

Introduction

Documentation is often treated as an afterthought, but it's a critical part of professional software development. Through maintaining projects over years, I've learned that good documentation is what makes the difference between a usable project and an abandoned one.

This article covers documentation best practices, from inline docstrings to comprehensive README files and API documentation.

Why Documentation Matters

Good documentation:

Reduces onboarding time - New team members get up to speed faster
Enables self-service - Users answer their own questions
Preserves knowledge - Capture decisions and context
Improves code quality - Writing docs forces clearer thinking

Docstrings

PEP 257 Standards

def calculate_discount(price: Decimal, discount_rate: float) -> Decimal:
    """
    Calculate the discounted price.

    Applies a percentage discount to the original price and returns
    the final amount after discount.

    Args:
        price: The original price before discount.
        discount_rate: The discount as a decimal (e.g., 0.10 for 10%).

    Returns:
        The price after applying the discount.

    Raises:
        ValueError: If discount_rate is negative or greater than 1.

    Examples:
        >>> calculate_discount(Decimal("100.00"), 0.10)
        Decimal('90.00')
        >>> calculate_discount(Decimal("50.00"), 0.25)
        Decimal('37.50')
    """
    if not 0 <= discount_rate <= 1:
        raise ValueError(f"discount_rate must be between 0 and 1, got {discount_rate}")
    
    discount = price * Decimal(str(discount_rate))
    return price - discount

Google Style Docstrings

def fetch_users(
    active_only: bool = True,
    limit: int = 100,
    offset: int = 0,
) -> list[User]:
    """Fetch users from the database.

    Retrieves a paginated list of users, optionally filtering by active status.
    Results are ordered by creation date, newest first.

    Args:
        active_only: If True, only return active users. Defaults to True.
        limit: Maximum number of users to return. Defaults to 100.
        offset: Number of users to skip for pagination. Defaults to 0.

    Returns:
        A list of User objects matching the criteria.

    Raises:
        DatabaseError: If the database connection fails.
        ValueError: If limit is less than 1 or offset is negative.

    Example:
        >>> users = fetch_users(active_only=True, limit=10)
        >>> len(users)
        10
        >>> all(user.is_active for user in users)
        True
    """
    pass

Class Docstrings

class TaskManager:
    """Manages task lifecycle and persistence.

    The TaskManager provides a high-level interface for creating, updating,
    and querying tasks. It handles validation, persistence, and notification
    of task events.

    Attributes:
        repository: The underlying storage for tasks.
        notifier: Service for sending task notifications.

    Example:
        >>> manager = TaskManager(repository, notifier)
        >>> task = manager.create("Learn Python")
        >>> manager.complete(task.id)
        >>> task.is_completed
        True

    Note:
        This class is thread-safe for concurrent access.
    """

    def __init__(
        self,
        repository: TaskRepository,
        notifier: Notifier,
    ) -> None:
        """Initialize TaskManager with dependencies.

        Args:
            repository: Storage backend for task persistence.
            notifier: Service for sending notifications.
        """
        self._repository = repository
        self._notifier = notifier

Module Docstrings

"""
User authentication and authorization module.

This module provides functionality for:
- User authentication via password or OAuth
- Session management
- Permission checking and role-based access control

The module is designed to be backend-agnostic, supporting multiple
storage backends through the Repository pattern.

Example:
    >>> from auth import authenticate, check_permission
    >>> user = authenticate("[email protected]", "password123")
    >>> if check_permission(user, "admin:write"):
    ...     perform_admin_action()

Typical usage:
    1. Configure the authentication backend
    2. Use authenticate() for user login
    3. Use check_permission() for authorization

See Also:
    - auth.backends: Available authentication backends
    - auth.permissions: Permission constants
"""

from .authentication import authenticate, logout
from .authorization import check_permission, require_permission
from .session import Session, SessionManager

__all__ = [
    "authenticate",
    "logout", 
    "check_permission",
    "require_permission",
    "Session",
    "SessionManager",
]

README Files

README Structure

# Project Name

One-line description of what this project does.

## Overview

A paragraph explaining the project's purpose, who it's for, and why it exists.

## Features

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

## Quick Start

```bash
pip install project-name

from project_name import main_function

result = main_function()

Installation

Detailed installation instructions including prerequisites.

Usage

More comprehensive usage examples and common scenarios.

Configuration

Available configuration options and how to set them.

API Reference

Link to full API documentation or key endpoints.

Contributing

How to contribute to the project.

License

License information.


### Complete README Example

```markdown
# Task Manager CLI

A command-line task management application built with Python.

## Overview

Task Manager CLI helps you organize your work from the terminal. It supports 
creating, listing, completing, and organizing tasks with tags and due dates.

Built for developers who prefer staying in the terminal.

## Features

- ✅ Create and manage tasks
- 📅 Set due dates and reminders
- 🏷️ Organize with tags
- 📊 View task statistics
- 💾 Local SQLite storage
- 🔄 Sync with cloud (optional)

## Quick Start

```bash
# Install
pip install task-manager-cli

# Add a task
task add "Review pull request" --due tomorrow

# List tasks
task list

# Complete a task
task complete 1

Installation

Requirements

Python 3.11 or higher
pip or pipx

Install via pip

pip install task-manager-cli

Install via pipx (recommended)

pipx install task-manager-cli

Install from source

git clone https://github.com/username/task-manager-cli.git
cd task-manager-cli
pip install -e ".[dev]"

Usage

Creating Tasks

# Simple task
task add "Buy groceries"

# With due date
task add "Submit report" --due 2024-01-15

# With tags
task add "Fix login bug" --tag bug --tag urgent

# With priority
task add "Call client" --priority high

Listing Tasks

# All tasks
task list

# Filter by status
task list --status pending
task list --status completed

# Filter by tag
task list --tag work

# Due today
task list --due today

Managing Tasks

# Complete a task
task complete 1

# Edit a task
task edit 1 --title "Updated title"

# Delete a task
task delete 1

# View task details
task show 1

Configuration

Task Manager CLI uses a configuration file at ~/.config/task-manager/config.toml.

# Default configuration
[general]
default_priority = "medium"
date_format = "%Y-%m-%d"

[display]
colors = true
compact = false

[storage]
database_path = "~/.local/share/task-manager/tasks.db"

Environment Variables

Variable

Description

Default

TASK_MANAGER_DB

Database path

~/.local/share/task-manager/tasks.db

TASK_MANAGER_CONFIG

Config file path

~/.config/task-manager/config.toml

NO_COLOR

Disable colors

Not set

Development

Setup

# Clone the repository
git clone https://github.com/username/task-manager-cli.git
cd task-manager-cli

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# All tests
pytest

# With coverage
pytest --cov=src/task_manager

# Specific test file
pytest tests/test_cli.py

Code Quality

# Lint
ruff check src tests

# Format
ruff format src tests

# Type check
mypy src

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see LICENSE for details.

Acknowledgments

Click for CLI framework
Rich for terminal formatting
SQLite for local storage


## API Documentation

### Auto-generating Documentation

```python
# Using Sphinx with autodoc

# docs/conf.py
project = 'Task Manager'
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',  # For Google-style docstrings
    'sphinx.ext.viewcode',
]

# Generate API docs
# sphinx-apidoc -o docs/api src/task_manager

MkDocs with mkdocstrings

# mkdocs.yml
site_name: Task Manager
theme:
  name: material

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: true
            docstring_style: google

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api/

Inline API Documentation

"""
API Reference
=============

This module provides the public API for task management.

TaskManager
-----------

.. autoclass:: task_manager.TaskManager
   :members:
   :undoc-members:
   :show-inheritance:

Task
----

.. autoclass:: task_manager.Task
   :members:
   :show-inheritance:

Functions
---------

.. autofunction:: task_manager.create_task
.. autofunction:: task_manager.complete_task
"""

Keeping Documentation Updated

Documentation as Code

# .github/workflows/docs.yml
name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: pip install -e ".[docs]"
      
      - name: Build documentation
        run: mkdocs build --strict
      
      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        run: mkdocs gh-deploy --force

Doctest for Verified Examples

def add_numbers(a: int, b: int) -> int:
    """Add two numbers together.
    
    Examples:
        >>> add_numbers(1, 2)
        3
        >>> add_numbers(-1, 1)
        0
        >>> add_numbers(0, 0)
        0
    """
    return a + b

# Run doctests
python -m doctest module.py

# With pytest
pytest --doctest-modules src/

Pre-commit Documentation Checks

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pycqa/pydocstyle
    rev: 6.3.0
    hooks:
      - id: pydocstyle
        args: [--convention=google]
  
  - repo: https://github.com/econchick/interrogate
    rev: 1.5.0
    hooks:
      - id: interrogate
        args: [--fail-under=80, src/]

Documentation Patterns

Architecture Decision Records (ADRs)

# ADR 001: Use SQLite for Local Storage

## Status

Accepted

## Context

We need to store tasks locally with support for querying and filtering.
Options considered:
- JSON files
- SQLite database
- PostgreSQL

## Decision

We will use SQLite for local storage.

## Rationale

- No external database server required
- Single file storage, easy to backup
- Full SQL query support
- Good Python support via sqlite3
- Sufficient performance for our use case

## Consequences

### Positive
- Zero configuration for users
- Portable database file
- ACID compliance

### Negative
- Limited concurrent write support
- No built-in cloud sync
- May need migration path for future

## Alternatives Considered

### JSON Files
- Simpler but no query support
- Would require loading entire dataset

### PostgreSQL
- Too heavy for CLI tool
- Requires external server

Changelog

# 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
- Cloud sync feature (experimental)

## [1.2.0] - 2024-01-15

### Added
- Due date reminders
- Task priority levels
- Export to JSON/CSV

### Changed
- Improved list command performance
- Updated CLI help text

### Fixed
- Date parsing for non-US locales
- Unicode handling in task titles

## [1.1.0] - 2024-01-01

### Added
- Tag support for tasks
- Filter by multiple criteria

### Security
- Fixed SQL injection vulnerability in search

## [1.0.0] - 2023-12-01

### Added
- Initial release
- Basic task CRUD operations
- SQLite storage

Contributing Guide

# Contributing to Task Manager

Thank you for your interest in contributing! This guide will help you get started.

## Code of Conduct

Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## How to Contribute

### Reporting Bugs

1. Check if the bug is already reported in [Issues](../../issues)
2. If not, create a new issue with:
   - Clear description of the bug
   - Steps to reproduce
   - Expected vs actual behavior
   - Environment details (OS, Python version)

### Suggesting Features

1. Open an issue with the "enhancement" label
2. Describe the feature and its use case
3. Be open to discussion about implementation

### Pull Requests

1. Fork the repository
2. Create a feature branch from `main`
3. Make your changes following our style guide
4. Add tests for new functionality
5. Update documentation as needed
6. Submit a pull request

## Development Setup

```bash
git clone https://github.com/username/task-manager.git
cd task-manager
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

Code Style

Follow PEP 8
Use type hints
Write docstrings for public functions
Keep functions small and focused

Testing

Write tests for all new features
Maintain test coverage above 80%
Run pytest before submitting PR

Documentation

Update docstrings for API changes
Update README for user-facing changes
Add entries to CHANGELOG.md


## Practical Exercise

### Exercise 1: Write Complete Docstrings

```python
# Add comprehensive docstrings to these functions

def send_email(to, subject, body, cc=None, attachments=None):
    """[Add docstring here]"""
    pass


class EmailClient:
    """[Add docstring here]"""
    
    def __init__(self, smtp_host, smtp_port, username, password):
        """[Add docstring here]"""
        pass
    
    def connect(self):
        """[Add docstring here]"""
        pass
    
    def send(self, message):
        """[Add docstring here]"""
        pass

Exercise 2: Create a README

Create a README for a hypothetical URL shortener project:

Name: ShortLink
Features: Shorten URLs, custom aliases, click tracking
Tech: Python, FastAPI, Redis
Installation, usage, configuration sections

Documentation Checklist

Use this checklist for projects:

Key Takeaways

Write docstrings first - They help clarify your design
README is your landing page - Make it welcoming and clear
Keep docs with code - Documentation as code stays updated
Automate verification - Use doctests and CI checks
Document decisions - ADRs preserve context for future

What's Next?

With well-documented code, let's focus on handling the unexpected. In Article 9: Error Handling and Logging, we'll cover exception handling, structured logging, and debugging strategies.

This article is part of the Software Engineering 101 series.

PreviousArticle 7: Advanced Testing Strategies NextArticle 9: Error Handling and Logging

Last updated 15 hours ago

hashtagIntroduction

hashtagWhy Documentation Matters

hashtagDocstrings

hashtagPEP 257 Standards

hashtagGoogle Style Docstrings

hashtagClass Docstrings

hashtagModule Docstrings

hashtagREADME Files

hashtagREADME Structure

hashtagInstallation

hashtagUsage

hashtagConfiguration

hashtagAPI Reference

hashtagContributing

hashtagLicense

hashtagInstallation

hashtagRequirements

hashtagInstall via pip

hashtagInstall via pipx (recommended)

hashtagInstall from source

hashtagUsage

hashtagCreating Tasks

hashtagListing Tasks

hashtagManaging Tasks

hashtagConfiguration

hashtagEnvironment Variables

hashtagDevelopment

hashtagSetup

hashtagRunning Tests

hashtagCode Quality

hashtagContributing

hashtagLicense

hashtagAcknowledgments

hashtagMkDocs with mkdocstrings

hashtagInline API Documentation

hashtagKeeping Documentation Updated

hashtagDocumentation as Code

hashtagDoctest for Verified Examples

hashtagPre-commit Documentation Checks

hashtagDocumentation Patterns

hashtagArchitecture Decision Records (ADRs)

hashtagChangelog

hashtagContributing Guide

hashtagCode Style

hashtagTesting

hashtagDocumentation

hashtagExercise 2: Create a README

hashtagDocumentation Checklist

hashtagKey Takeaways

hashtagWhat's Next?

Introduction

Why Documentation Matters

Docstrings

PEP 257 Standards

Google Style Docstrings

Class Docstrings

Module Docstrings

README Files

README Structure

Installation

Usage

Configuration

API Reference

Contributing

License

Installation

Requirements

Install via pip

Install via pipx (recommended)

Install from source

Usage

Creating Tasks

Listing Tasks

Managing Tasks

Configuration

Environment Variables

Development

Setup

Running Tests

Code Quality

Contributing

License

Acknowledgments

MkDocs with mkdocstrings

Inline API Documentation

Keeping Documentation Updated

Documentation as Code

Doctest for Verified Examples

Pre-commit Documentation Checks

Documentation Patterns

Architecture Decision Records (ADRs)

Changelog

Contributing Guide

Code Style

Testing

Documentation

Exercise 2: Create a README

Documentation Checklist

Key Takeaways

What's Next?