Documentation/Jutsu/Notetaker/ skills /documentation-linking

📖 documentation-linking

Use when creating bidirectional links between code and documentation. Covers link patterns, documentation references, context preservation across artifacts, and maintaining synchronization between code and docs.


Overview

Creating and maintaining bidirectional links between code and documentation for AI-assisted development.

Bidirectional Linking

Code → Documentation

Link from code to relevant documentation:

/**
 * Implements the authentication flow described in:
 * @doc docs/architecture/authentication.md#oauth-flow
 * @api-spec api/openapi.yaml#/components/securitySchemes/oauth2
 * @decision-record docs/decisions/003-oauth-provider.md
 *
 * Related endpoints:
 * - POST /auth/login (login initiation)
 * - GET /auth/callback (OAuth callback)
 * - POST /auth/refresh (token refresh)
 */
export class AuthenticationService {
  // Implementation
}

Documentation → Code

Link from documentation to implementing code:

# Authentication Flow

Our OAuth 2.0 authentication flow is implemented in:

- Main logic: `src/services/AuthenticationService.ts`
- Routes: `src/routes/auth.ts:15-45`
- Middleware: `src/middleware/auth.ts:78`
- Tests: `tests/integration/auth.test.ts`

See also:
- Database schema: `migrations/003_create_users.sql`
- Configuration: `config/auth.yaml`

Link Formats

Absolute Links

# @doc /docs/database/migrations.md#schema-versioning
# Full path from repository root

Relative Links

// @doc ../../../docs/api/rest-endpoints.md#user-endpoints
// Relative to current file

Line-Specific Links

// @impl service/user_service.go:145-178
// Links to specific line range

Anchor Links

/// @doc architecture.md#data-flow-diagram
/// Links to specific section via anchor

Documentation Types

Architecture Documentation

/**
 * @arch-doc docs/architecture/system-overview.md
 * @component-diagram docs/diagrams/user-service.svg
 * @sequence-diagram docs/diagrams/login-flow.puml
 *
 * This service is part of the user management subsystem.
 * See architecture docs for component interactions and data flow.
 */
class UserService {
  // Implementation
}

API Documentation

# @api-doc docs/api/rest-api.md#POST-/users
# @openapi-spec api/openapi.yaml#/paths/~1users/post
# @example docs/examples/create-user.md
#
# REST endpoint for creating users. API contract is defined in OpenAPI spec.
# Changes to request/response format must update both code and spec.

@app.post("/users")
async def create_user(user: UserCreate) -> User:
    """
    @request-example:
      POST /users
      {
        "email": "user@example.com",
        "name": "John Doe"
      }

    @response-example:
      201 Created
      {
        "id": 123,
        "email": "user@example.com",
        "name": "John Doe",
        "created_at": "2025-12-04T10:00:00Z"
      }
    """
    # Implementation

Decision Records

/**
 * @decision-record docs/decisions/005-caching-strategy.md
 *
 * DECISION: Using Redis for caching instead of in-memory cache
 * RATIONALE: Need distributed cache for horizontal scaling
 * DATE: 2025-11-15
 *
 * This implements the caching strategy defined in ADR-005.
 * Cache invalidation rules:
 * 1. Time-based: 5 minute TTL
 * 2. Event-based: Invalidate on user.updated event
 * 3. Manual: Admin can clear cache via /admin/cache/clear
 */
public class CacheService {
    // Implementation following decision record
}

Test Documentation

// @test-doc docs/testing/integration-tests.md#database-tests
// @test-data fixtures/users.json
// @test-cases tests/integration/user_test.go
//
// Integration tests use Docker containers for PostgreSQL.
// Test data is loaded from fixtures before each test.
// See test documentation for setup instructions.

func TestUserRepository(t *testing.T) {
    // Test implementation
}

Runbook Links

# @runbook docs/runbooks/incident-response.md#database-failover
# @monitoring dashboard/database-health
# @alerts alerts/database-connection-pool
#
# Database connection pool monitoring and failover logic.
# If pool exhaustion alert fires, follow runbook for mitigation steps.

class DatabaseConnectionPool:
    """
    @metric connection_pool_active (gauge)
    @metric connection_pool_idle (gauge)
    @metric connection_pool_wait_time (histogram)

    Alert thresholds:
    - connection_pool_active > 90% of max_connections for 5min
    - connection_pool_wait_time p95 > 1000ms
    """
    # Implementation

Cross-Referencing Patterns

Issue/Ticket References

/**
 * @issue https://github.com/org/repo/issues/1234
 * @pr https://github.com/org/repo/pull/1245
 * @jira PROJ-567
 *
 * Implements user story PROJ-567: Real-time notification system
 * See issue #1234 for requirements discussion
 * See PR #1245 for implementation review and feedback
 */
class NotificationService {
  // Implementation
}

Wiki/Confluence Links

# @wiki https://wiki.company.com/display/ENG/Data+Pipeline
# @confluence https://company.atlassian.net/wiki/spaces/ARCH/pages/123456
#
# Data pipeline architecture documented in company wiki.
# This implements the extraction phase of the ETL pipeline.

class DataExtractor:
    # Implementation

External Resources

/// @rfc https://tools.ietf.org/html/rfc7519
/// @spec https://openid.net/specs/openid-connect-core-1_0.html
/// @tutorial https://auth0.com/docs/secure/tokens/json-web-tokens
///
/// JWT implementation following RFC 7519 specification.
/// Supports OpenID Connect extensions per OIDC Core spec.

pub struct JwtToken {
    // Implementation
}

Synchronization Strategies

Automated Link Validation

Script to validate documentation links:

#!/bin/bash
# validate-doc-links.sh

# Extract all @doc references from code
grep -r "@doc " src/ | while read -r line; do
  doc_path=$(echo "$line" | sed -n 's/.*@doc \([^[:space:]]*\).*/\1/p')
  file_path=$(echo "$doc_path" | cut -d'#' -f1)

  if [ ! -f "$file_path" ]; then
    echo "ERROR: Broken doc link: $doc_path"
    echo "  Referenced in: $line"
  fi
done

Documentation Coverage

Track which code has documentation links:

# doc-coverage.py
import re
from pathlib import Path

def has_doc_link(file_path):
    """Check if file contains @doc annotations"""
    with open(file_path) as f:
        content = f.read()
    return '@doc' in content or '@api-doc' in content

# Calculate coverage
source_files = list(Path('src').rglob('*.py'))
with_docs = [f for f in source_files if has_doc_link(f)]
coverage = len(with_docs) / len(source_files) * 100

print(f"Documentation link coverage: {coverage:.1f}%")

Reverse Link Tracking

Maintain reverse index in documentation:

# Authentication Documentation

## Referenced By

This document is referenced by the following code files:

- `src/services/AuthenticationService.ts:15` - Main auth logic
- `src/middleware/auth.ts:34` - Auth middleware
- `src/routes/auth.ts:8` - Auth routes

<!-- AUTO-GENERATED: Do not edit manually -->
<!-- Generated by: scripts/update-doc-references.sh -->

Link Maintenance

Automated Updates

Git pre-commit hook to check doc links:

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating documentation links..."

# Check for broken @doc links
broken_links=$(grep -r "@doc " src/ | while read -r line; do
  doc_path=$(echo "$line" | sed -n 's/.*@doc \([^[:space:]]*\).*/\1/p')
  file_path=$(echo "$doc_path" | cut -d'#' -f1)

  if [ ! -f "$file_path" ]; then
    echo "$line"
  fi
done)

if [ -n "$broken_links" ]; then
  echo "ERROR: Broken documentation links found:"
  echo "$broken_links"
  exit 1
fi

Link Deprecation

Mark outdated links:

/**
 * @doc docs/old-approach.md [DEPRECATED: See docs/new-approach.md]
 * @doc-current docs/new-approach.md
 *
 * This implementation is being migrated to new approach.
 * Old documentation kept for reference during transition.
 * Migration deadline: 2026-01-01
 */

Versioned Documentation

Link to specific documentation versions:

# @doc docs/v2/api-reference.md
# @doc-version 2.3.0
#
# This code implements API v2.3.0 specification.
# For v3.0.0 changes, see docs/v3/migration-guide.md

class APIv2Handler:
    # Implementation

Documentation Patterns

README Links

Link to README for module documentation:

// @readme ./README.md
//
// Package userservice provides user management functionality.
// See README.md for usage examples and configuration options.

package userservice

Example Code

Link to runnable examples:

/// @example examples/basic-usage.rs
/// @example-advanced examples/advanced-patterns.rs
///
/// Basic usage example shows simple CRUD operations.
/// Advanced example demonstrates batching and transactions.

pub struct Repository<T> {
    // Implementation
}

Tutorial Links

/**
 * @tutorial docs/tutorials/getting-started.md
 * @tutorial-video https://youtube.com/watch?v=abc123
 * @interactive-demo https://demo.example.com
 *
 * New to this library? Start with the getting started tutorial.
 * Video walkthrough available for visual learners.
 */
export class SDK {
  // Implementation
}

Anti-Patterns

Don't

❌ Use brittle relative links

# @doc ../../../../../../../docs/guide.md
# Bad - breaks easily when files move

❌ Link to outdated documentation

// @doc docs/deprecated-api.md
// Bad - should link to current docs or mark as deprecated

❌ Create circular documentation dependencies

// file1.go
// @doc docs/file2.md

// docs/file2.md references file3.go
// file3.go references file1.go
// Bad - circular reference makes navigation confusing

Do

✅ Use repository-relative paths

# @doc docs/guide.md
# Good - stable even if current file moves

✅ Keep links current

// @doc docs/current-api.md
// @doc-history docs/api-v1.md [DEPRECATED]
// Good - clear which is current

✅ Create clear navigation hierarchy

// @doc-parent docs/architecture/overview.md
// @doc-current docs/architecture/auth-service.md
// @doc-related docs/architecture/user-service.md
// Good - clear hierarchy and relationships

Integration Examples

Markdown Documentation

# User Service

## Implementation

The user service is implemented across several files:

### Core Logic

- [`src/services/UserService.ts`](../src/services/UserService.ts) - Main service class
- [`src/models/User.ts`](../src/models/User.ts) - User model
- [`src/repositories/UserRepository.ts`](../src/repositories/UserRepository.ts) - Data access

### API Layer

- [`src/routes/users.ts`](../src/routes/users.ts#L15-L45) - REST endpoints
- [`src/controllers/UserController.ts`](../src/controllers/UserController.ts) - Request handling

### Tests

- [`tests/unit/UserService.test.ts`](../tests/unit/UserService.test.ts) - Unit tests
- [`tests/integration/users.test.ts`](../tests/integration/users.test.ts) - Integration tests

OpenAPI/Swagger

# api/openapi.yaml
paths:
  /users:
    post:
      summary: Create user
      description: |
        Creates a new user in the system.

        **Implementation:**
        - Handler: `src/handlers/users.go:CreateUser`
        - Validation: `src/validators/user.go:ValidateCreate`
        - Database: `src/repositories/user_repo.go:Insert`

        **Related Documentation:**
        - [User Management Guide](../docs/user-management.md)
        - [API Authentication](../docs/api-auth.md)

JSDoc/TypeDoc

/**
 * User authentication service
 *
 * @see {@link ../docs/architecture/auth-flow.md} for authentication flow diagram
 * @see {@link ../docs/api/auth-api.md} for API documentation
 *
 * @example
 * ```typescript
 * const auth = new AuthService();
 * const token = await auth.login(username, password);
 * ```
 *
 * @example
 * See {@link ../examples/auth-flow.ts} for complete authentication example
 */
export class AuthService {
  // Implementation
}

Related Skills

  • notetaker-fundamentals
  • code-annotation-patterns

Resources