Better developer onboarding experience needed

[peterjumpnl]

Developer onboarding is currently complex. I think this is a big hurdle for broader adoption.

The docs at https://www.mxcli.org/ are a nice step forward, but they are not optimized for time-to-first-success and more focused on explaining deep concepts. Multiple concepts are introduced at once (MDL, Mendix internals, AI tooling), early decisions are required (tooling choices), and visible results are delayed. This increases cognitive load and slows down even experienced developers.

The improvement should focus on use-case first documentation.

1. List units
2. Modify your Mendix project
3. Generate or update components

I like the setup of Laravel documentation for example: https://laravel.com/docs/13.x/installation

Key improvements:

• Structure docs in stages (basic → intermediate → advanced)
• Provide a 5-minute quickstart with copy-paste commands and expected output
• Hide advanced topics and conceptual explanations (MDL, architecture) from the initial flow

Additional gaps to address:

• Capability registry visibility: provide a clear, up-to-date overview of what mxcli can and cannot do (e.g. supported operations, limitations, edge cases). This reduces trial-and-error and sets correct expectations.
• LLM customization guidance: document how to steer or fine-tune generation towards project-specific conventions (naming, architecture, patterns). Currently unclear how teams can enforce consistency.
• Roadmap clarity: give an indication what capabilities are planned and expected timelines. This helps decide whether to adopt now or wait for specific features.

This is unrelated to any Mendix or MX CLI version.

[github-actions]

Issue Triage

Summary: The issue requests a better developer onboarding experience for mxcli by restructuring documentation into progressive stages, adding a quick‑start guide, and providing clearer capability, customization, and roadmap information.

Checklist (feature request):

• [✅] Use case – why the feature is needed / problem it solves
• [✅] Proposed syntax or behavior (if applicable)
• [✅] Mendix version relevance (if version‑specific)

Comment: The issue looks complete. Thanks for the detailed suggestion! 🙏

---

Automated triage via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Completeness Assessment

The enhancement request is clear about the goal (improve developer onboarding) but lacks specific details needed for implementation. To proceed, I need clarification on:

1. Documentation location: Should improvements be made to:

   • The public mxcli.org website (docs-site/src/ directory)?
   • Internal CLI help/documentation (cmd/mxcli/help.go, help_topics/)?
   • Both?

2. Capability registry visibility: What form should this take?

   • A new mxcli capabilities command?
   • Enhanced mxcli help output?
   • A dedicated capabilities page in documentation?
   • JSON/YAML output for programmatic consumption?

3. LLM customization guidance: What specific aspects need documentation?

   • How to fine-tune generation for naming conventions?
   • How to enforce architectural patterns?
   • How to provide project-specific examples to LLMs?
   • Should this reference existing skills like .claude/skills/write-microflows.md?

4. Roadmap format: Should this be:

   • A static ROADMAP.md file?
   • A section in documentation?
   • Generated from issue labels/milestones?
   • Include timelines or just feature lists?

5. Quickstart scope: What should the 5-minute quickstart cover?

   • Just installation and basic commands?
   • A complete end-to-end example (read project → modify → verify)?
   • Should it use a sample project or work with any Mendix project?

Without these details, I cannot provide a specific implementation plan. The request is well-motivated but needs scoping to be actionable.

Overlap Check

This is purely a documentation/enhancement request with no direct code overlap. However, related existing features include:

• Existing documentation:

  • docs/ directory with technical references
  • docs-site/src/ for user-facing documentation (likely powers mxcli.org)
  • CLI help system (cmd/mxcli/help.go, help_topics/)
  • Skill files in .claude/skills/ for task-specific guidance

• Capability discovery:

  • SHOW CATALOG TABLES lists queryable metadata
  • mxcli check --references validates MDL against project
  • mxcli report provides capability usage insights
  • No existing command lists all mxcli capabilities

• LLM guidance:

  • Existing skill files (.claude/skills/) provide LLM-friendly guidance
  • mxcli init sets up .claude/ folder with skills
  • No centralized documentation on customizing LLMs for project conventions

• Roadmap visibility:

  • GitHub issues/projects exist but not surfaced in docs
  • docs/11-proposals/ shows planned features
  • No consolidated, user-facing roadmap

Proposed MDL Syntax

Not applicable - this enhancement focuses on documentation and CLI UX, not MDL syntax changes.

Implementation Roadmap

Assuming documentation improvements to docs-site/ and CLI help system:

Phase 1: Quickstart & Core Documentation

1. Create 5-minute quickstart:

   • File: docs-site/src/getting-started/quickstart.md
   • Content: Copy-paste commands for:

     # Install mxcli
     go install github.com/mendix/modelsdk-go/cmd/mxcli@latest
     
     # Download sample project (or use existing)
     git clone https://github.com/mendix/sample-project.git
     cd sample-project
     
     # 5-minute workflow
     mxcli show entities -p app.mpr
     mxcli -p app.mpr -c "CREATE ENTITY MyModule.Test (Name: String(50));"
     mxcli check -p app.mpr  # Verify no errors

   • Include expected output screenshots
   • Add troubleshooting for common issues (Java version, mxbuild download)

2. Revise getting started guide:

   • File: docs-site/src/getting-started/index.md
   • Structure:
     • Stage 1: Installation & first commands (5 min)
     • Stage 2: Reading projects (SHOW commands)
     • Stage 3: Basic modifications (CREATE/ALTER)
     • Stage 4: Advanced features (microflows, pages)
     • Stage 5: Automation & CI/CD

Phase 2: Capability Registry

3. Add capabilities command:

   • File: cmd/mxcli/cmd_capabilities.go
   • Implement: mxcli capabilities [--format json|table] [--category <cat>]
   • Output: Lists all available MX CLI commands, MDL statements, and key features
   • Categories: project structure, domain model, microflows, pages, security, etc.

4. Enhance help system:

   • File: cmd/mxcli/help.go
   • Add "capabilities" topic to interactive help
   • Update mxcli help capabilities to show same output as CLI command

Phase 3: LLM & Roadmap Documentation

5. LLM customization guide:

   • File: docs-site/src/advanced/llm-customization.md
   • Content:
     • How to use .claude/skills/ for project conventions
     • Example: Creating a skill for company-specific naming rules
     • How to provide few-shot examples to LLMs
     • Reference to existing skills (write-microflows.md, create-page.md)

6. Roadmap documentation:

   • File: docs-site/src/project/roadmap.md
   • Content:
     • Near-term (0-3 months): Features in active development
     • Mid-term (3-6 months): Planned features with GitHub issue links
     • Long-term (6+ months): Vision and exploration areas
     • Update process: How community can influence roadmap

Phase 4: Integration & Validation

7. Update mxcli init:

   • File: cmd/mxcli/init.go
   • Add welcome message pointing to quickstart
   • Ensure .claude/ folder includes LLM customization template

8. Add documentation validation to CI:

   • File: .github/workflows/docs.yml
   • Job:
     • Link checker (markdown-link-check)
     • Example validation (run quickstart commands in CI)
     • Spell check (cspell)

BSON Investigation

Not applicable - this is documentation work.

Testing Strategy

Documentation Validation

1. Quickstart verification:

   • Add to CI: Script that runs exact quickstart commands in ephemeral environment
   • Verify: No errors, expected output patterns, project modifications succeed
   • Test against multiple Mendix versions (if version-specific)

2. Capabilities command testing:

   • Unit test: cmd/mxcli/cmd_capabilities_test.go
   • Verify: All major feature areas listed, correct formatting
   • Integration test: mxcli capabilities --format json parses correctly

3. Link and example validation:

   • GitHub Action: markdown-link-check for all docs
   • Example runner: Extract code blocks from docs, verify they parse/execute
   • Focus on quickstart and tutorial examples

Manual Validation

1. User testing:

   • Observe new developers attempting quickstart
   • Measure time-to-first-success (target: <5 minutes)
   • Collect feedback on confusing steps

2. Documentation review:

   • Monthly: Verify roadmap accuracy
   • Quarterly: Check capabilities output against actual features
   • After each release: Update quickstart if breaking changes

Gotchas & Risks

Documentation-Specific Risks

1. Quickstart fragility:

   • Risk: Sample project becomes outdated or incompatible
   • Mitigation: Use minimal, version-agnostic project; test against latest stable Mendix
   • Risk: mxbuild download fails in CI/airgapped environments
   • Mitigation: Document offline installation; provide pre-downloaded mxbuild option

2. Capabilities command maintenance:

   • Risk: Command lags behind actual features
   • Mitigation: Auto-generate from command definitions; add CI check for missing commands
   • Risk: Output too verbose for quick scanning
   • Mitigation: Implement --category filtering and --format options

3. LLM guidance effectiveness:

   • Risk: Guidance too generic to be useful
   • Mitigation: Include concrete examples from real projects
   • Risk: Users don't discover .claude/skills/ mechanism
   • Mitigation: Promote via mxcli init output and quickstart

4. Roadmap accuracy:

   • Risk: Creates false expectations if timelines slip
   • Mitigation: Use qualitative timelines (near/mid/long-term); emphasize "planned, not guaranteed"
   • Risk: Maintenance overhead
   • Mitigation: Tie to GitHub projects/milestones for semi-automatic generation

Implementation Risks

1. Scope creep:

   • Risk: Documentation effort expands beyond agreed scope
   • Mitigation: Define MVP (quickstart + capabilities command) first; iterate based on feedback
   • Risk: Neglecting code improvements while focusing on docs
   • Mitigation: Treat as parallel track; ensure core functionality continues to receive attention

2. Inconsistent messaging:

   • Risk: Different docs sections contradict each other
   • Mitigation: Single source of truth for key concepts; use includes/templates where possible
   • Risk: CLI help and docs-site diverge
   • Mitigation: Share content where feasible; validate consistency in CI

3. Accessibility oversights:

   • Risk: Code samples assume Unix-like environment
   • Mitigation: Include Windows equivalents (PowerShell/Cmd) where significantly different
   • Risk: Examples require paid Mendix licenses
   • Mitigation: Use Mendix Community Edition or trial projects in examples

This implementation focuses on measurable onboarding improvements while leveraging existing documentation infrastructure. Success will be measured by reduced time-to-first-success and fewer basic usage questions in community channels.

---

Automated guide via OpenRouter — workflow source

[ako]

Thanks for the thoughtful feedback @peterjumpnl. You're right that time-to-first-success is the key metric for onboarding.

What we have today

The docs site already has a progressive tutorial structure:

1. Setting Up → Installation → Opening a Project → REPL
2. Exploring → SHOW commands → DESCRIBE/SEARCH → SHOW STRUCTURE
3. First Changes → Entity → Microflow → Page → Validation
4. AI Assistants → Claude Code → Skills → MDL+AI Workflow

But as you note, the entry point doesn't optimize for quick wins. You have to read through setup, conceptual explainers, and tooling choices before seeing a result.

What we agree on

1. 5-minute quickstart — should be the first thing a developer sees. Copy-paste commands, expected output, visible result. No conceptual explanations needed at this stage.

2. Capability visibility — we're actively working on this. The version-aware agent support proposal includes SHOW FEATURES commands and a structured feature registry. This directly addresses "what can mxcli do?"

3. LLM customization — the .claude/skills/ mechanism already supports project-specific conventions, but it's not documented as a customization pathway. We should add a "Customizing for your project" guide.

4. Roadmap — fair point. The proposals in docs/11-proposals/ exist but aren't surfaced to users. We'll add a roadmap page.

Concrete next steps

• Add a Quickstart page as the first tutorial entry (before "Setting Up")
• Add a Capabilities page listing what mxcli can do, organized by use case
• Add a Customizing AI Generation guide covering skills, CLAUDE.md, and conventions
• Add a Roadmap page summarizing active proposals
• Restructure the landing page to lead with "What can I do in 5 minutes?" not "What is MDL?"

The Laravel docs are a good reference — their "Installation" page gets you to a running app in ~10 commands with visible output at each step.