docs: [#14] improve documentation organization and markdownlint configuration

josecelano · josecelano · commit a4a890c3e504 · 2025-07-25T17:34:02.000+01:00
- Create dedicated ADR documentation (docs/adr/README.md)
  - Add ADR guidelines, template, and lessons learned
  - Move ADR list from docs/README.md to dedicated location
  - Document best practices for keeping ADRs focused

- Configure global table line length exclusion in markdownlint
  - Update .markdownlint.json to exclude tables from MD013 rule
  - Create .markdownlint.md with configuration documentation
  - Update .github/copilot-instructions.md with simplified table guidance
  - Remove unnecessary markdownlint ignore blocks from existing tables

- Document SSH host key verification troubleshooting
  - Create docs/infrastructure/ssh-host-key-verification.md
  - Provide comprehensive solution for VM development warnings

- Improve documentation structure and navigation
  - Update docs/README.md with cleaner organization
  - Add cross-references and proper categorization
  - Include reference to markdownlint configuration guidelines

Benefits:
- Tables automatically ignore line length limits (no manual ignore blocks needed)
- Cleaner markdown files without visual clutter
- Better organized ADR documentation with clear guidelines
- Comprehensive troubleshooting documentation for common issues
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -300,6 +300,8 @@ The twelve-factor **Build, Release, Run** stages apply to the application deploy
 - **Structure**: Use consistent heading hierarchy
 - **Links**: Prefer relative links for internal documentation
 - **Code blocks**: Always specify language for syntax highlighting
+- **Tables**: Tables automatically ignore line length limits (configured globally in
+  `.markdownlint.json`). No special formatting required for table line lengths.
 
 #### Automated Linting
 
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -1,7 +1,8 @@
 {
     "default": true,
     "MD013": {
-        "line_length": 100
+        "line_length": 100,
+        "tables": false
     },
     "MD031": true,
     "MD032": true,
diff --git a/.markdownlint.md b/.markdownlint.md
@@ -0,0 +1,38 @@
+# Markdownlint Configuration
+
+This file documents the markdownlint configuration for the project.
+
+## Line Length Handling
+
+The project enforces a 100-character line limit for markdown files (`MD013` rule).
+Tables are automatically excluded from this limit to maintain readability.
+
+### Table Line Length Configuration
+
+Tables are configured to ignore line length limits globally via the `.markdownlint.json` configuration:
+
+```json
+"MD013": {
+    "line_length": 100,
+    "tables": false
+}
+```
+
+This means:
+
+- **Regular text**: Must stay within 100 characters per line
+- **Tables**: Can exceed line length limits without linting errors
+- **Code blocks**: Follow normal line length rules
+
+### Alternative Approach
+
+If you need to disable line length for specific non-table content, you can still use
+markdownlint ignore blocks:
+
+```markdown
+<!-- markdownlint-disable MD013 -->
+
+Very long line content that needs to exceed the normal limit
+
+<!-- markdownlint-enable MD013 -->
+```
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,4 @@
-# Documentation Structure
+docs/README.md# Documentation Structure
 
 This directory contains general cross-cutting documentation for the Torrust
 Tracker Demo project.
@@ -14,20 +14,10 @@ This directory currently contains cross-cutting documentation:
 
 ### 📋 [`adr/`](adr/) (Architecture Decision Records)
 
-**Current ADRs:**
-
-- [ADR-001: Makefile Location](adr/001-makefile-location.md) - Decision to keep
-  Makefile at repository root level
-- [ADR-002: Docker for All Services](adr/002-docker-for-all-services.md) - Decision
-  to use Docker for all services including UDP tracker
-- [ADR-003: Use MySQL Over MariaDB](adr/003-use-mysql-over-mariadb.md) - Decision
-  to use MySQL instead of MariaDB for database backend
-- [ADR-004: Configuration Approach Files vs Environment Variables]
-  (adr/004-configuration-approach-files-vs-environment-variables.md) -
-  Configuration approach decision for application settings
-- [ADR-005: Sudo Cache Management for Infrastructure Operations]
-  (adr/005-sudo-cache-management-for-infrastructure-operations.md) -
-  Proactive sudo cache management for better UX during testing
+**Important architectural decisions** that affect the system structure, behavior, or
+development process.
+
+📖 **[See ADR README](adr/README.md)** for complete list, guidelines, and best practices.
 
 ### 📅 [`plans/`](plans/) (Ongoing Plans and Roadmaps)
 
@@ -43,6 +33,30 @@ This directory currently contains cross-cutting documentation:
 - [Phase 1: MySQL Migration](issues/12-use-mysql-instead-of-sqlite-by-default.md) -
   Detailed implementation plan for database migration from SQLite to MySQL
 
+### 🏗️ [`infrastructure/`](infrastructure/) (Infrastructure Documentation)
+
+**Cross-cutting infrastructure documentation** - For infrastructure-related
+documentation that affects the project as a whole or provides reference materials.
+
+**Current Infrastructure Documentation:**
+
+- [SSH Host Key Verification](infrastructure/ssh-host-key-verification.md) -
+  Explains and resolves SSH host key verification warnings in VM development
+
+### 📚 [`guides/`](guides/) (User and Developer Guides)
+
+**High-level guides and end-to-end workflows** - For complete procedures
+that span multiple components.
+
+**Current Guides:**
+
+- [Integration Testing Guide](guides/integration-testing-guide.md) - Step-by-step
+  guide for running integration tests following twelve-factor methodology
+- [Quick Start Guide](guides/quick-start.md) - Fast setup guide for getting
+  started quickly
+- [Smoke Testing Guide](guides/smoke-testing-guide.md) - End-to-end testing
+  using official Torrust client tools
+
 ### 🔧 [`refactoring/`](refactoring/) (Refactoring Documentation)
 
 **Major refactoring initiatives and changes** - Documentation of significant
@@ -110,3 +124,5 @@ When adding new documentation:
 - **ADRs**: Should follow standard ADR template format and affect multiple layers
 - **Theory**: Should explain concepts clearly with examples when possible
 - **Benchmarks**: Should include methodology, environment, and reproducible results
+- **Markdown Tables**: For tables exceeding line length limits, see
+  [`.markdownlint.md`](../.markdownlint.md) for proper formatting guidelines
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -0,0 +1,180 @@
+# Architecture Decision Records (ADRs)
+
+This directory contains Architecture Decision Records (ADRs) for the Torrust Tracker Demo project.
+
+## What are ADRs?
+
+Architecture Decision Records document important architectural decisions made during the project
+lifecycle. They provide context, rationale, and consequences of decisions that affect the
+system's structure, behavior, or development process.
+
+## ADR Guidelines
+
+### When to Create an ADR
+
+Create an ADR for decisions that:
+
+- **Affect multiple system components** or development workflows
+- **Have significant long-term implications** for the project
+- **Involve trade-offs** between different approaches
+- **Need to be communicated** to the team and future contributors
+- **May be questioned** or reversed in the future
+
+### When NOT to Create an ADR
+
+Avoid creating ADRs for:
+
+- **Implementation details** specific to a single component
+- **Temporary workarounds** or quick fixes
+- **Obvious technical choices** with no reasonable alternatives
+- **Operational procedures** (use operational documentation instead)
+
+### ADR Structure
+
+Each ADR should follow this template:
+
+```markdown
+# ADR-XXX: [Decision Title]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded]
+
+## Context
+
+[Describe the problem, constraints, and forces at play]
+
+## Decision
+
+[State the decision clearly and concisely]
+
+## Alternatives Considered
+
+[List other options that were considered and why they were rejected]
+
+## Rationale
+
+[Explain why this decision was made]
+
+## Consequences
+
+### Positive
+
+- [List benefits and positive outcomes]
+
+### Negative
+
+- [List costs, risks, and negative impacts]
+
+### Neutral
+
+- [List neutral consequences and trade-offs]
+
+## Implementation Details
+
+[Optional: Include relevant implementation specifics]
+
+## Monitoring
+
+[How will we measure if this decision is working]
+
+## Related Decisions
+
+[Link to related ADRs]
+
+## References
+
+[Links to supporting documentation, discussions, etc.]
+```
+
+## Lessons Learned
+
+### Keep ADRs Focused
+
+**❌ Bad Practice**: Mixing multiple unrelated decisions in a single ADR
+
+**✅ Good Practice**: Each ADR should address a single architectural decision
+
+**Example**: ADR-005 originally mixed sudo cache management with SSH host key verification.
+These are separate infrastructure concerns and should be documented separately:
+
+- Sudo cache management → ADR (architectural decision)
+- SSH host key verification → Operational documentation (troubleshooting guide)
+
+### Separate Concerns by Type
+
+| Documentation Type       | Purpose                        | Location               | Example             |
+| ------------------------ | ------------------------------ | ---------------------- | ------------------- |
+| **ADR**                  | Record architectural decisions | `docs/adr/`            | Database choice     |
+| **Operational Docs**     | Solve immediate problems       | `docs/infrastructure/` | SSH troubleshooting |
+| **Implementation Plans** | Detail feature implementation  | `docs/issues/`         | Development plans   |
+| **User Guides**          | End-to-end workflows           | `docs/guides/`         | Testing procedures  |
+
+### Scope and Audience
+
+- **ADRs**: For contributors understanding design decisions
+- **Operational Docs**: For users encountering specific problems
+- **Guides**: For users following complete procedures
+
+## Current ADRs
+
+### 📋 Active ADRs
+
+- [ADR-001: Makefile Location](001-makefile-location.md) - Decision to keep
+  Makefile at repository root level
+- [ADR-002: Docker for All Services](002-docker-for-all-services.md) - Decision
+  to use Docker for all services including UDP tracker
+- [ADR-003: Use MySQL Over MariaDB](003-use-mysql-over-mariadb.md) - Decision
+  to use MySQL instead of MariaDB for database backend
+- [ADR-004: Configuration Approach Files vs Environment Variables]
+  (004-configuration-approach-files-vs-environment-variables.md) -
+  Configuration approach decision for application settings
+- [ADR-005: Sudo Cache Management for Infrastructure Operations]
+  (005-sudo-cache-management-for-infrastructure-operations.md) -
+  Proactive sudo cache management for better UX during testing
+
+### 📊 ADR Statistics
+
+- **Total ADRs**: 5
+- **Status**: All Accepted
+- **Coverage**: Infrastructure (3), Application (1), Development Workflow (1)
+
+## Contributing
+
+### Creating a New ADR
+
+1. **Identify the decision** that needs documentation
+2. **Check existing ADRs** to avoid duplication
+3. **Determine ADR number** (next sequential number)
+4. **Use the template** provided above
+5. **Focus on a single decision** - avoid mixing multiple concerns
+6. **Get team review** before marking as "Accepted"
+7. **Update this README** to include the new ADR in the list
+
+### Updating Existing ADRs
+
+- **Status changes**: Update status from "Proposed" to "Accepted"
+- **Superseding**: When replacing an ADR, update the old one's status to "Superseded"
+- **References**: Add references when decisions are implemented or referenced
+
+### Best Practices
+
+1. **Write for the future**: Assume readers don't have current context
+2. **Include alternatives**: Show what options were considered
+3. **Be honest about trade-offs**: Document both benefits and costs
+4. **Keep it concise**: Focus on the decision, not implementation details
+5. **Link related decisions**: Cross-reference related ADRs
+6. **Update when necessary**: ADRs can evolve as understanding improves
+
+## Templates and Examples
+
+- **Template**: Use the structure outlined in "ADR Structure" above
+- **Good Examples**: ADR-001 (clear trade-offs), ADR-003 (thorough alternatives analysis)
+- **Lessons Learned**: See ADR-005 for an example of how to keep focused scope
+
+## Related Documentation
+
+- [Main Documentation Guide](../README.md) - Overall documentation structure
+- [Infrastructure Documentation](../../infrastructure/docs/) - Infrastructure-specific docs
+- [Application Documentation](../../application/docs/) - Application-specific docs
+- [Guides](../guides/) - End-to-end procedures and workflows
diff --git a/docs/infrastructure/ssh-host-key-verification.md b/docs/infrastructure/ssh-host-key-verification.md
