RFC: Documentation Website with Docusaurus

[javierbrea]

Status: 🚧 Request for Comments - Open for community feedback

Summary

This RFC proposes creating a dedicated documentation website for the @boundaries ecosystem using Docusaurus. The website will provide a centralized, well-organized, and versioned documentation hub for all packages under the @boundaries scope, including the ESLint plugin, core libraries, and future tools.

Key Changes

1. New documentation website: Create a comprehensive documentation site hosted separately from the main repository README
2. Docusaurus implementation: Utilize Docusaurus as the static site generator with built-in versioning support
3. Restructured documentation: Organize documentation into logical sections
4. Version management: Support multiple versions of documentation aligned with plugin releases
5. Ecosystem-wide documentation: Unified documentation for all future @boundaries packages and tools
6. Simplified README: Keep the main repository README concise with quickstart examples and links to the full documentation site

Motivation

Current Limitations

The current documentation approach has several challenges as the project grows:

1. README File Size and Maintainability

The main repository README is becoming increasingly extensive, making it:

• Difficult to navigate and find specific information
• Challenging to maintain as a single file
• Hard to organize with complex architectural patterns and use cases
• Overwhelming for new users looking for quick start information

2. Lack of Documentation Versioning

Currently, there's no easy way for users to:

• Access documentation for specific versions of the plugin
• Understand what features are available in their installed version
• Preview upcoming features in the "next" version
• Compare configuration between versions during upgrades

3. Limited Organization and Discovery

With a single README file, it's difficult to:

• Separate different types of documentation (tutorials, guides, API reference, recipes)
• Provide progressive disclosure of complexity (basic → intermediate → advanced)
• Create cross-references between related topics

4. Ecosystem Growth Challenges

With the planned expansion of the @boundaries ecosystem (mentioned in RFC for Plugin Rename):

• @boundaries/eslint-plugin (ESLint plugin - runs rules)
• @boundaries/elements (Core library - element logic)
• @boundaries/playground (Future: interactive configuration tool)
• @boundaries/graph (Future: dependency graph visualization)

Each tool will need its own documentation, but they should all be discoverable from a single unified location. A monolithic README cannot effectively serve this need.

5. Recipe and Pattern Documentation

The new features proposed in recent RFCs (multi-dimensional classification, object-based selectors) introduce powerful capabilities that benefit from:

• Real-world usage recipes and patterns
• Step-by-step implementation guides
• Interactive examples
• Use case-driven documentation

These are difficult to present effectively in a single README file.

Why a Dedicated Documentation Website?

1. Better User Experience

A documentation website provides:

• Structured navigation: Sidebar with clear hierarchy and sections
• Search functionality: Full-text search across all documentation
• Progressive disclosure: Start with basics, drill down into advanced topics
• Visual hierarchy: Better formatting, syntax highlighting, and visual aids
• Responsive design: Optimized for different screen sizes and devices

2. Versioning Support

Docusaurus provides built-in versioning that enables:

• Multiple version support: Users can switch between versions easily
• Next/unreleased version: Document upcoming features in a "next" version
• Version dropdown: Easy navigation between different versions

3. Ecosystem Integration

A centralized documentation site can:

• House documentation for all @boundaries packages in one place
• Provide consistent navigation across different tools
• Enable cross-linking between related packages
• Present a unified brand and user experience

4. Enhanced Content Types

A website enables richer content:

• Tutorials: Step-by-step guides for common scenarios
• Recipes: Detailed patterns and use cases with code examples
• API Reference: Auto-generated or structured API documentation
• Interactive examples: Future integration with playground tool

Why Docusaurus?

Docusaurus is an excellent choice for this project because:

1. Built for documentation: Specifically designed for project documentation
2. React-based: Familiar technology stack for customization
3. Versioning built-in: Native support for multiple documentation versions
4. MDX support: Write documentation in Markdown with React components
5. Fast and modern: Static site generation with excellent performance
6. Active community: Well-maintained by Meta with strong community support
7. Search integration: Built-in search with Algolia DocSearch support
8. Customizable: Extensive theming and plugin system
9. Industry standard: Used by many popular open-source projects (React, Redux, Jest, etc.)

Detailed Design

1. Documentation Structure

The documentation will be organized into clear sections:

Landing Page

• Brief introduction to the @boundaries ecosystem
• Quick links to getting started
• Feature highlights
• Link to GitHub repository

Getting Started

• Installation: Package installation instructions
• Quick Start: Minimal working example
• Basic Configuration: Step-by-step setup guide
• First Rules: Implementing your first boundary rules

Guides

• Element Descriptions: Detailed explanation of describing elements using configuration
• Element Selectors: How to select elements for rules
• Rules Overview: Comprehensive guide to all available rules
• Advanced Patterns: Complex configuration scenarios
• TypeScript Setup: TypeScript-specific configuration
• Capture Values: Using captured values in rules
• Multi-dimensional Classification: Using categories (from RFC RFC: Multi-dimensional Element Classification with Categories #369)

Recipes

Practical, copy-paste examples for common architectural patterns:

• Atomic Design Pattern: Components, atoms, molecules, organisms
• Domain-Driven Design: Domain boundaries and context mapping
• Feature-Sliced Design: Modern frontend architecture
• Monorepo Setup: Managing boundaries in monorepos
• ...etc.

API Reference

• Configuration Settings: All available settings options
• Rules: Detailed documentation for each rule
  • Rule purpose and use cases
  • Configuration options
  • Examples
  • Common patterns
• Descriptor Syntax: Complete descriptor reference
• Selector Syntax: Complete selector reference

Ecosystem

• @boundaries/elements: Core elements package documentation
• @boundaries/playground: Interactive configuration tool (future)
• @boundaries/graph: Dependency visualization (future)

Migration Guides

• Version-specific migration guides with breaking changes
• Configuration examples showing before/after
• Troubleshooting common migration issues

3. Versioning Strategy

The documentation will follow this versioning approach:

Current Version (e.g., 5.0)

• Latest stable release documentation
• Accessible at the root URL: https://boundaries-docs.io/docs/
• Represents the most recently released version

Next Version (Unreleased)

• Documentation for upcoming features
• Accessible at: https://boundaries-docs.io/docs/next/
• Contains documentation for features in RFCs and development
• Updated continuously as development progresses

Previous Versions (e.g., 4.0, 3.0)

• Historical documentation for older versions
• Accessible at: https://boundaries-docs.io/docs/4.0/, etc.
• Read-only, preserved for users on older versions

Version Dropdown

• Prominent version selector in the navigation bar
• Allows users to switch between versions easily
• Indicates which is the current/latest version

4. Version Release Workflow

When releasing a new version of the plugin:

1. Before Release:

   • Ensure "next" documentation is complete and accurate
   • Review all documentation changes

2. During Release:

   • Run Docusaurus versioning command: npm run docusaurus docs:version X.Y
   • This creates a snapshot of current docs in versioned_docs/version-X.Y/
   • Updates versions.json to include the new version
   • The "next" docs become the new working branch

3. After Release:

   • Deploy the updated documentation site
   • The new version becomes the default/latest version
   • Previous stable version is still accessible
   • "Next" version now represents the upcoming release

Migration Plan

Phase 1: Initial Setup (v6.0-beta.1)

• Set up Docusaurus project structure
• Create basic documentation structure
• Migrate existing README content to appropriate sections
• Create getting started guide
• Document current plugin version (v5.x)
• Next version starts with upcoming v6.0 features

Phase 2: Publish v6.0

• Finalize documentation for v6.0 features
• Create version snapshot for v6.0

Maintenance and Updates

Documentation Updates

• Documentation changes should be part of the PR process
• Code changes should include corresponding documentation updates
• Documentation reviews should be part of code reviews

Version Management

• Create new version snapshot with each major/minor release
• Maintain all previous major versions
• Archive old minor versions if necessary (replace major versions with latest minor)

Community Contributions

• Clear contribution guidelines for documentation
• Templates for new recipe submissions
• Review process for community-contributed content

Benefits

For Users

1. Easier to find information: Structured navigation and search
2. Version-specific documentation: Access docs for their installed version
3. Better learning curve: Progressive disclosure from basic to advanced
4. More examples: Rich recipe library for common patterns
5. Preview upcoming features: See what's coming in "next" version

For Maintainers

1. Easier to maintain: Structured content vs. monolithic README
2. Better organization: Separate concerns (guides, reference, recipes)
3. Ecosystem growth: Easy to add documentation for new tools

For the Project

1. Better discoverability: Improved SEO and search engine ranking
2. Professional presence: Industry-standard documentation approach
3. Ecosystem cohesion: Unified documentation for all packages
4. Long-term sustainability: Scalable documentation structure

---

Thank you for reviewing this proposal! Your feedback is crucial for creating a documentation experience that serves the community's needs. Please share your thoughts on the structure, content organization, and any concerns you might have.