Proposal to guide structure: Supporting two distinct user journeys

[jgumbley]

Based on analyzing support threads, FAQs, and common user queries, our docs could better serve two distinct user personas:

• Vibe Coder discovers AI coding through demos and videos - "I want AI to build cool stuff with me!" They're excited to experiment but need a safe, guided path to success. Often not a professional developer and may be new to AI tools.
• Expert Customizer dives deep into technical capabilities - "I have a vision for a custom agentic workflow and want to build it in Roo." They want a clear map of system capabilities and how they can be composed together.

Two Different Approaches

For Vibe Coder: A Guided Flow

• From "Create your first AI app" through to experimenting with features as needed.
• Each step builds naturally from playing with the tool.
• Uses friendly language and real-world examples like "Let's build a first app together" instead of technical terms.
• Includes basic troubleshooting steps and clear pathways to Discord community support when stuck.

For Expert: A Technical Map

• Clear signposts to key system areas: Mode System, Prompt Engineering, MCP Architecture, Integration Points etc.
• Each section assumes technical proficiency and focuses on capabilities and connections rather than step-by-step guidance.
• Links to high-quality external resources where appropriate (e.g., MCP specs).
• Directs to GitHub for deeper engagement and encourages PRs for missing functionality.

The Next Step

1. Begin refactoring towards one entry point that splits existing content into two distinct documentation styles - a guided journey for Vibe Coder, a technical map for experts.
2. As we improve content in each path develop consistent terminology that speaks to its audience.
3. Secondary: Weave in FAQ content to support these paths naturally.

Open Question
Supporting two distinct user types creates additional maintenance burden. Should we focus more heavily on one persona? Current usage suggests both paths are valuable, but this trade-off deserves discussion.

[cfdude]

@jgumbley thanks for putting this together, this is really helpful information. As someone that spends a ton of time providing support on Discord, I think in this case, we don't create Documentation for two different audiences. While we may have two distinct personas, I think both personas value input in different ways. For example, for the Vibe Coders, I think it makes sense to put together step-by-step guides or how-to videos for small projects that can be completed in a day or so. I think the focus would be around different ways to incorporate different parts of Roo Code so if you go through an entire series you become more of the Expert user, even though you are not an expert coder.

I think for the Expert user persona I think they want two different things. I think they want to understand new features and how to best take advantage of them. Experts often try out local models so we should expand not just Ollama but others like LM Studio and more. I also think Expert personas would also want to expand and see working examples of workflow improvement too. These things can be accomplished in video format as well or step-by-step guides (or both). I see this persona as leveraging video/step-by-step as well as vanilla documentation.

I think the path forward for documentation sake, is well-defined vanilla documentation devoid of skewing towards multiple personas on how the product works. We need clear instructions on Roo's functions, inputs, outputs etc and pictures / images of what the product looks like so users know where in the product to find things.