IT-Journey

Open-Source IT Education Platform

Status: Living

Version: 2025-11-29

Auto-Generated: ✅

0. WHY

Build IT-Journey — an open-source educational platform that democratizes IT education through gamified quests, practical tutorials, and AI-enhanced learning experiences, transforming complete beginners into skilled IT professionals.

KFI: 100% of learners who complete a quest path can demonstrate measurable skill improvement through hands-on projects in their portfolio.

1. MVP (Minimum Viable Promise)

As a learner / contributor / educator, I want:

• ✅ Gamified learning quests with progressive difficulty (Level 0000 → advanced)
• ✅ Practical tutorials that build real-world portfolio projects
• ✅ Multi-platform support (macOS, Windows, Linux, Cloud)
• ✅ AI-enhanced development workflows and automation
• ✅ Jekyll-based static site with GitHub Pages deployment
• ✅ Automated quality assurance (link checking, content validation)
• 🔄 Interactive terminal interface (journey.sh) for navigation
• 🔜 Certification tracking and skill progression metrics

Current Content Status

2. UX (User eXperience Flow)

graph TD
    A[New Learner] --> B[Visit IT-Journey Site]
    B --> C{Choose Path}
    C -->|Beginner| D[Zero to Hero Guide]
    C -->|Intermediate| E[Learning Quests]
    C -->|Advanced| F[Contribute & Create]
    D --> G[Complete Foundational Quests]
    E --> G
    G --> H[Build Portfolio Projects]
    H --> I[Skill Progression Tracked]
    I --> J[Community Recognition]
    F --> K[Create Quests/Tutorials]
    K --> J
    J --> L[🔄 Continue Learning Journey]
    L --> C

User Journeys

Beginner Path:

1. Discover: Visit site → Browse quests by level
2. Learn: Start with Level 0000 quests → Follow step-by-step tutorials
3. Practice: Complete hands-on exercises → Build first projects
4. Progress: Track skill development → Unlock advanced content

Contributor Path:

1. Explore: Review existing content → Identify gaps or improvements
2. Create: Write new quests/tutorials → Follow content guidelines
3. Submit: Open PR → Get community feedback
4. Iterate: Refine based on learner outcomes

3. API (Atomic Programmable Interface)

Site Navigation

CLI Tools

# Interactive terminal interface
./journey.sh

# Local development
bundle exec jekyll serve --config _config.yml,_config_dev.yml

# Docker development
docker compose up jekyll

# Quest validation
docker compose run quest-validator

# PRD synchronization
docker compose run prd-machine ./scripts/prd-machine/prd-machine sync

# Link health check
python3 scripts/link-checker.py --scope website

GitHub Actions Workflows

4. NFR (Non-Functional Realities)

5. EDGE (Exceptions, Dependencies, Gotchas)

Dependencies

• Ruby 3.2+: Jekyll runtime
• Jekyll 3.9+: Static site generator
• Bundler: Ruby dependency management
• Python 3.8+: Automation scripts and validation
• Docker: Containerized development environment
• Git: Version control and GitHub integration

Platform Requirements

Gotchas

• Jekyll versions: Pinned to 3.9.x for GitHub Pages compatibility
• Ruby versions: Use rbenv/rvm for version management
• Large repos: Initial clone may take time; use sparse checkout if needed
• Binary files: Images/media should go in assets/ only
• Frontmatter: All content files require valid YAML frontmatter

Recent Issues Detected

• FIX: Bug fix suggests incomplete requirement: fix(quest): correct invalid Liquid template in bash-scripting permalink
  • Action: Consider if original requirement needs clarification
• FIX: Bug fix suggests incomplete requirement: fix: replace invalid Liquid template syntax in bash-scripting quest permalink
  • Action: Consider if original requirement needs clarification
• FIX: Bug fix suggests incomplete requirement: fix: update last modified date in CONTRIBUTING.md and add first-time contributor fast track section
  • Action: Consider if original requirement needs clarification
• FIX: Bug fix suggests incomplete requirement: fix: update last modified date and permalink format in bash scripting quest
  • Action: Consider if original requirement needs clarification

6. OOS (Out Of Scope)

IT-Journey explicitly does NOT:

• ❌ Provide paid certifications or credentials
• ❌ Offer live instructor-led training
• ❌ Host user-generated content without review
• ❌ Store personal user data or accounts
• ❌ Provide enterprise or commercial support
• ❌ Replace formal education programs
• ❌ Guarantee job placement or outcomes

Focus Areas

The platform focuses on:

• ✅ Self-paced, asynchronous learning
• ✅ Open-source community contributions
• ✅ Practical, portfolio-building projects
• ✅ Free, accessible educational content

7. ROAD (Roadmap)

Upcoming Features

• Enhanced quest progression tracking
• Community discussion integration
• Skill assessment and badging
• Mobile-optimized experience
• AI-powered content recommendations
• Integration with external learning platforms

8. RISK (Top Risks)

Risk Monitoring

The platform monitors health through:

• Guardian 2.0: Daily link health checks with AI-powered analysis
• PRD Machine: Automated requirements freshness tracking
• GitHub Actions: Build validation and content checks
• Community feedback: Issue tracking and discussion monitoring

9. DONE (Definition of Done)

Success Criteria

• Learners complete quests with demonstrable skill improvements
• Contributors can easily add content following clear guidelines
• Site remains accessible and fast across all platforms
• Content stays current with regular community contributions
• Quality assurance catches issues before they impact learners

Validation Metrics

When these criteria are met, IT-Journey fulfills its mission:

Democratizing IT education through open-source learning, gamified experiences, and community-driven content.

Keep learning. Keep building. Keep sharing. 🚀