Phase 1: Foundation (Weeks 1-2)

Overview

Phase 1 establishes the foundation for all future improvements. These initiatives are prerequisite for Phase 2 and provide the core infrastructure (test framework, documentation standards, navigation consistency) needed for quality improvements.

Timeline: Weeks 1-2 | Effort: 40-60 hours | Impact: HIGH | Status: Pending

Initiative P1-1: Create Standardized Documentation Template

Objective

Create a reusable .template.md file that defines the standard structure for all documentation pages. This ensures consistency across the 102-file codebase and makes new contributions easier.

Deliverables

.template.md - Reusable template with standard sections
Migration guide - Instructions for updating existing files
Style guide - Specific conventions for each section type

Template Structure (to be created)

# Topic Title

## Overview
Brief description of what this page covers. 1-2 paragraphs.

## When to Use
Use cases and scenarios where this feature/concept applies.

## Syntax / Examples
(Varies by topic - code examples, configuration, etc.)

### Basic Example
Clear, simple example with expected output.

### Advanced Example
More complex real-world usage pattern.

## Comparison Table
How this relates to alternatives or similar concepts.

| Feature | Option A | Option B | Notes |
|---------|----------|----------|-------|
| ... | ... | ... | ... |

## Related Topics
- [Link to related](../path)
- [Link to related](../path)

## PHP Version
**Minimum:** PHP 8.0 (or 7.4, 5.3.6+, etc.)
**Deprecated:** Yes/No, if applicable

## See Also
- [Official PHP Documentation](https://php.net)
- [Related Moodle API](https://docs.moodle.org)

Success Criteria

✅ Template file created and documented
✅ Migration guide written with before/after examples
✅ Applied to at least 10 existing pages as proof-of-concept
✅ All modified pages render correctly: mkdocs build --clean

Commands

# Create template
# File: docs/.template.md

# Test template on sample files
mkdocs build --clean
mkdocs serve -a 127.0.0.1:8000

# Visit sample pages to verify structure works well

Dependencies

None (first initiative)

Notes

Keep template flexible enough for different topic types (functions, classes, concepts, etc.)
Include comments in template explaining each section
Document common exceptions (e.g., API reference pages may have different structure)

Initiative P1-2: Expand Test Suite (1 → 15+ Tests)

Objective

Replace the single smoke test with a comprehensive test suite covering link validation, navigation integrity, responsive design, search functionality, and performance.

Deliverables

15+ Playwright tests covering key functionality
Test documentation - How to run, add, and maintain tests
CI integration (optional) - GitHub Actions workflow for automated testing

Test Categories to Implement

1. Link Validation (3-4 tests)

All internal links are valid (no 404s)
All external links return 200-399 status (option: skip fragile external links)
Links in mkdocs.yml match actual files
Relative paths work correctly

Navigation sidebar renders without errors
All nav items match mkdocs.yml
Navigation order matches mkdocs.yml
Breadcrumb navigation works correctly

3. Content & Formatting (2-3 tests)

Code blocks render with syntax highlighting
Tables display correctly
Images load correctly
Headings generate valid anchors

4. Responsive Design (1-2 tests)

Page renders on mobile (375px width)
Page renders on tablet (768px width)
Page renders on desktop (1280px width)

5. Search Functionality (1-2 tests)

Search index is generated
Search returns results for common terms
Search results are clickable

6. Performance (1-2 tests)

Homepage loads in < 3 seconds
Average page loads in < 2 seconds
Build completes without errors

Success Criteria

✅ 15+ tests created and passing
✅ All tests in tests/ directory
✅ npx playwright test runs without errors
✅ Test documentation added
✅ (Optional) CI workflow created

Commands

# Install dependencies
npm install
npx playwright install --with-deps

# Create new test files in tests/
# tests/links.spec.ts
# tests/navigation.spec.ts
# tests/content.spec.ts
# tests/responsive.spec.ts
# tests/search.spec.ts
# tests/performance.spec.ts

# Run tests
npx playwright test

# Run tests with UI
npx playwright test --ui

# Run specific test file
npx playwright test tests/links.spec.ts

Dependencies

None (can run in parallel with other P1 initiatives)

Notes

Start with most critical tests (link validation, navigation)
Add more granular tests as suite stabilizes
Consider using test fixtures for common setup
Document how to run tests locally and in CI

Objective

Standardize the mkdocs.yml navigation structure for professional appearance and better user experience.

Issues to Fix

Capitalization - Inconsistent Title Case
Current: "Time n Date" → Target: "Date & Time"
Current: "Constant : " → Target: "Constants"
Current: "Globals :" → Target: "Globals"
Language - Remove informal/abbreviated terms
Current: "Time n Date" → Target: "Date & Time"
Current: "phpstan" → Target: "PHPStan"
Current: "Tiller" → Target: "Tiller" (check if this needs explanation)
Spacing & Punctuation - Consistent formatting
Remove trailing spaces
Consistent spacing around punctuation
No unnecessary colons or spaces
Section Organization - Logical grouping
Verify related topics are grouped
Check indentation is consistent (2 spaces)

Changes Required in mkdocs.yml

Current	Target	Reason
"Time n Date"	"Date & Time"	Formal, consistent capitalization
"Constant :"	"Constants"	Remove trailing punctuation
"Globals :"	"Globals"	Remove trailing punctuation
"Error and Exceptions :"	"Error and Exceptions"	Remove trailing punctuation
"Config Variables :"	"Configuration Variables"	More descriptive
"Mail:"	"Mail"	Remove trailing punctuation

Success Criteria

✅ All nav entries use Title Case consistently
✅ No trailing punctuation in nav labels
✅ Consistent spacing (2 spaces for indentation)
✅ No unnecessary punctuation or abbreviations
✅ Navigation renders correctly: mkdocs serve

Commands

# Edit mkdocs.yml nav section
# Make consistency changes

# Verify navigation renders correctly
mkdocs serve -a 127.0.0.1:8000

# Check for any broken links from navigation changes
npx playwright test tests/navigation.spec.ts

Dependencies

None (can run in parallel with other P1 initiatives)

Notes

Keep a before/after list of all changes
Verify site generation has no warnings
Test navigation on all devices (mobile, tablet, desktop)
Ensure all renamed sections still match file paths

Initiative P1-4: Add PHP Version Indicators

Objective

Tag all features and concepts by their minimum PHP version requirement (8.0+, 8.1+, 8.2+, 7.4, etc.). This helps users understand compatibility and feature availability.

Deliverables

Version badges - Visual indicators in documentation
README update - Features section with version requirements
Compatibility matrix - Key features by PHP version
Updated pages - All relevant docs tagged with versions

Implementation Approach

1. Version Badge HTML (in Markdown)

<span class="php-badge php-80">PHP 8.0+</span>

<span class="php-badge php-81">PHP 8.1+</span>

<span class="php-badge php-82">PHP 8.2+</span>

<span class="php-badge deprecated">Deprecated (PHP 7.4)</span>

2. CSS for Badges (add to mkdocs.yml or custom CSS)

.php-badge {
  display: inline-block;
  padding: 2px 8px;
  border-radius: 3px;
  font-size: 12px;
  font-weight: bold;
  margin-right: 4px;
}

.php-80 {
  background-color: #4169E1;
  color: white;
}

.php-81 {
  background-color: #4A90E2;
  color: white;
}

.php-82 {
  background-color: #50A0FF;
  color: white;
}

.deprecated {
  background-color: #FF6B6B;
  color: white;
}

3. Pages to Update (Priority)

High Priority:
Classes/phpEnums.md (PHP 8.1+)
Classes/phpAttributes.md (PHP 8.0+)
Func/phpMatch.md (PHP 8.0+, if exists)
Func/phpConstructor.md (Constructor promotion - PHP 8.0+)
Medium Priority:
All Func/ pages (tag minimum versions)
All Classes/ pages (tag minimum versions)
PR/ pages with version-specific content
Optional:
Moodle pages (if Moodle has version dependencies)

4. README.md Update

Add version information to Features section:

## Features

- **~102 documented topics** covering PHP basics to advanced concepts
- **Modern PHP 8.x focus**
  - PHP 8.2 features
  - PHP 8.1 features (Enums, Fibers, Arrays/collection functions)
  - PHP 8.0 features (Attributes, Constructor Promotion, Match Expressions)
  - PHP 7.4 support (Typed properties, Arrow functions)
- **Moodle development** documentation with API references
- ... rest of features

Success Criteria

✅ Version badges created and styled
✅ All features tagged with minimum PHP version
✅ README Features section includes version info
✅ Compatibility matrix created
✅ At least 20 pages updated with version tags
✅ Site builds and displays correctly: mkdocs build --clean

Commands

# Edit README.md - add version info to Features section

# Edit relevant docs - add version badges to pages
# Examples:
# - Classes/phpEnums.md
# - Classes/phpAttributes.md
# - Classes/phpConstructor.md
# - Func/ pages with version-specific content

# Create compatibility matrix (could be new page or README section)

# Build and verify
mkdocs build --clean
mkdocs serve -a 127.0.0.1:8000

# Test navigation changes
npx playwright test

Dependencies

None (can run in parallel with other P1 initiatives)

Notes

Research official PHP version requirements for each feature
Consider backward compatibility notes (e.g., "PHP 5.3.6+")
Make badges non-intrusive but clearly visible
Update as new PHP versions are released

Phase 1 Summary & Checklist

Completion Checklist

P1-1: Doc Template - .template.md created, migration guide written, applied to 10 pages
P1-2: Test Suite - 15+ tests created, all passing, documentation added
P1-3: Navigation - mkdocs.yml standardized, site builds clean, navigation renders correctly
P1-4: PHP Versions - Version badges implemented, 20+ pages tagged, README updated

Validation

# Run final validation
mkdocs build --clean          # Should complete without errors
npx playwright test           # All tests should pass
mkdocs serve -a 127.0.0.1:8000  # Manual spot-check critical pages

Commits

Expected commits for Phase 1: 1. [P1-doc-template] Create standardized documentation template 2. [P1-expand-tests] Expand test suite to 15+ tests 3. [P1-fix-nav] Standardize mkdocs.yml navigation consistency 4. [P1-php-version-badges] Add PHP version indicators to documentation

Next Steps

Once Phase 1 completes: - Mark all P1 initiatives as done in SQL database - Begin Phase 2 (Organization) initiatives - Phase 2 will depend on P1 completion for template and standards

Resources

Template inspiration: See .template.md (to be created)
Style guide: Improvement documentation
Test framework: Playwright documentation (https://playwright.dev)
PHP version info: https://www.php.net/manual/en/

Questions?

Refer to: - Improvement documentation - Full project context - Implementation guidance - Community-specific guidance - plan.md (session) - Complete improvement strategy

Phase 1: Foundation (Weeks 1-2)

Overview

Initiative P1-1: Create Standardized Documentation Template

Objective

Deliverables

Template Structure (to be created)

Success Criteria

Commands

Dependencies

Notes

Initiative P1-2: Expand Test Suite (1 → 15+ Tests)

Objective

Deliverables

Test Categories to Implement

1. Link Validation (3-4 tests)

2. Navigation Integrity (3-4 tests)

3. Content & Formatting (2-3 tests)

4. Responsive Design (1-2 tests)

5. Search Functionality (1-2 tests)

6. Performance (1-2 tests)

Success Criteria

Commands

Dependencies

Notes

Initiative P1-3: Fix Navigation Consistency

Objective

Issues to Fix

Changes Required in mkdocs.yml

Success Criteria

Commands

Dependencies

Notes

Initiative P1-4: Add PHP Version Indicators

Objective

Deliverables

Implementation Approach

1. Version Badge HTML (in Markdown)

2. CSS for Badges (add to mkdocs.yml or custom CSS)

3. Pages to Update (Priority)

4. README.md Update

Success Criteria

Commands

Dependencies

Notes

Phase 1 Summary & Checklist

Completion Checklist

Validation

Commits

Next Steps

Resources

Questions?