Skip to content

Commit 8f334f5

Browse files
hannesrudolphhannesrudolph
authored
docs(cloud): trim UI narration across Roo Code Cloud pages; keep screenshots and anchors (#341)
- billing-subscriptions, dashboard, login, roomote-control, task-sharing, task-sync, overview - add value-first rules to docs writer playbook (.roo/) - clarify browser vs IDE capability in Roomote Control and overview Addresses feedback: remove screen narration while keeping images.
1 parent 25ad684 commit 8f334f5

File tree

11 files changed

+169
-116
lines changed

11 files changed

+169
-116
lines changed

‎.roo/rules-documentation-writer/1_writing_style.xml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,23 @@
6262
<principle name="utility">
6363
<rule>Focus on what the user can do and why it matters. Provide actionable steps.</rule>
6464
</principle>
65+
66+
<principle name="value_filter">
67+
<rule>Keep only what changes decisions, prevents mistakes, or unlocks outcomes. Cut narration of obvious UI.</rule>
68+
<keep>
69+
<item>Why it matters (value/outcome; 1–3 sentences at the top)</item>
70+
<item>Decision points and trade-offs (e.g., Pro vs free, security implications)</item>
71+
<item>Non-obvious behavior, caveats, limits, prerequisites</item>
72+
<item>Short, actionable steps; error handling and recovery</item>
73+
</keep>
74+
<cut>
75+
<item>Listing every visible control or tab on a page</item>
76+
<item>Describing screenshots (“This page shows…”, “It includes…”) without decisions or implications</item>
77+
<item>Explaining basic concepts common to developers</item>
78+
<item>Redundant restatement of labels already visible in screenshots</item>
79+
</cut>
80+
</principle>
81+
6582
<principle name="consistency">
6683
<rule>When editing a document, use its existing style, structure, and format as a guideline for any updates. Do not make major changes unless explicitly asked.</rule>
6784
<discovery_approach>
@@ -70,6 +87,20 @@
7087
<step>Match the existing style in your edits</step>
7188
</discovery_approach>
7289
</principle>
90+
91+
<principle name="voice_style">
92+
<rule>Bold, honest, human. No fluff, no fake hype.</rule>
93+
<do>
94+
<item>Short, punchy sentences. Speak like a helpful colleague.</item>
95+
<item>Expose real value. If it matters, state it clearly; if not, leave it out.</item>
96+
<item>Be excited when the feature earns it. Be candid about limits.</item>
97+
</do>
98+
<dont>
99+
<item>Don’t use buzzwords, clickbait, or corporate tone.</item>
100+
<item>Don’t exaggerate beyond the truth—real impact sells itself.</item>
101+
<item>Don’t narrate the screen. Focus on decisions and outcomes.</item>
102+
</dont>
103+
</principle>
73104
</core_principles>
74105

75106
<banned_language>
@@ -95,6 +126,33 @@
95126
<guideline>Use structured headings, lists, and short paragraphs for scannability.</guideline>
96127
<guideline>Provide clear, copy-pasteable code snippets.</guideline>
97128
<guideline>Assume user familiarity with basic concepts. Do not over-explain.</guideline>
129+
130+
<page_skeleton>
131+
<section order="1" name="why_it_matters">Explain the outcome and value in 1–3 sentences.</section>
132+
<section order="2" name="what_you_can_do">Concrete capabilities and decision points; link to authoritative references instead of duplication.</section>
133+
<section order="3" name="quickstart">Minimal steps to success (include only non-obvious choices).</section>
134+
<section order="4" name="limits_and_pricing">Important limits, access requirements, pricing—only what affects decisions.</section>
135+
<section order="5" name="troubleshooting">Common failure modes and fixes.</section>
136+
</page_skeleton>
137+
138+
<screenshot_policy>
139+
<rule>Only include screenshots when they clarify a decision, show non-obvious state, or demonstrate outcome.</rule>
140+
<limits>
141+
<maxPerSection>1</maxPerSection>
142+
<maxPerPage>3</maxPerPage>
143+
</limits>
144+
<prohibitions>
145+
<item>No narration of on-screen labels or obvious layout.</item>
146+
<item>No screenshot that repeats text already stated without adding decision context.</item>
147+
</prohibitions>
148+
<requirements>
149+
<item>Alt text describes action/outcome, not the UI chrome.</item>
150+
<item>Prefer width="800" unless smaller improves readability.</item>
151+
<item>Use captions or surrounding text to explain the decision/implication.</item>
152+
<item>Follow Docusaurus image rules; see rules in 2_docusaurus_conventions.xml.</item>
153+
</requirements>
154+
</screenshot_policy>
155+
98156
<discovery_approach>
99157
<step>Before formatting new content, examine existing documentation for:
100158
- Heading hierarchy patterns (H1, H2, H3 usage)

‎.roo/rules-documentation-writer/2_docusaurus_conventions.xml‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,31 @@
3535
<step>Check existing documentation for image reference patterns</step>
3636
<step>Follow the established convention</step>
3737
</discovery_steps>
38+
39+
<policy>
40+
<when_to_use>
41+
<item>Clarify a decision point or non-obvious UI state</item>
42+
<item>Demonstrate outcome/results that text alone cannot convey</item>
43+
</when_to_use>
44+
<avoid>
45+
<item>Narrating obvious UI (“This page shows…”, “It includes…”) without decisions or implications</item>
46+
<item>Listing every field/tab in a screen</item>
47+
</avoid>
48+
<limits>
49+
<maxPerSection>1</maxPerSection>
50+
<maxPerPage>3</maxPerPage>
51+
</limits>
52+
<alt_text>
53+
<rule>Describe the action or outcome, not the chrome. Example: "Toggle Roomote Control to enable remote tasks".</rule>
54+
</alt_text>
55+
<width_default>800</width_default>
56+
<format>Use HTML img tags per project rules. See Image Tag Format in .roorules.</format>
57+
</policy>
58+
3859
<example>
3960
<![CDATA[
40-
<!-- First discover the actual image path structure, then use it -->
41-
<img src="/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="600" />
61+
<!-- First discover the actual image path structure, then use it -->
62+
<img src="/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="600" />
4263
]]>
4364
</example>
4465
</rule>

‎.roo/rules-documentation-writer/3_validation_enforcement.xml‎

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,43 @@
8282
</enforcement>
8383
</gate>
8484

85+
<gate name="value_filter_gate" type="CRITICAL">
86+
<description>Enforces value-first writing and bans obvious-UI narration.</description>
87+
<requirements>
88+
<requirement>Include a brief "Why it matters" section or opener (1–3 sentences) that frames value/outcomes.</requirement>
89+
<requirement>Document decision points/trade-offs where the user must choose (e.g., Pro vs free, security implications).</requirement>
90+
<requirement>Remove or condense any enumeration of on-screen elements unless each item carries a decision, consequence, or non-obvious behavior.</requirement>
91+
<requirement>Apply screenshot limits (≤1 per section, ≤3 per page) and ensure alt text describes action/outcome.</requirement>
92+
</requirements>
93+
<evidence>
94+
<item>Checklist confirming presence of "Why it matters" and decisions</item>
95+
<item>Notes on removed UI narration and reasons</item>
96+
<item>Screenshot count and alt-text review</item>
97+
</evidence>
98+
<enforcement>
99+
If requirements are not met:
100+
- Block the edit and return a summary of violations with specific locations.
101+
- Require revision to pass this gate before proceeding.
102+
</enforcement>
103+
</gate>
104+
105+
<gate name="obvious_ui_narration_blocker" type="CRITICAL">
106+
<description>Blocks screen narration that restates visible UI without adding decisions or implications.</description>
107+
<blocked_phrases examples="non-exhaustive">
108+
<phrase>This page shows</phrase>
109+
<phrase>It includes</phrase>
110+
<phrase>The page displays</phrase>
111+
<phrase>List of</phrase>
112+
</blocked_phrases>
113+
<exceptions>
114+
<exception>Allowed only when each listed item includes why it matters, a decision, or an implication.</exception>
115+
</exceptions>
116+
<enforcement>
117+
If narration-only content is detected:
118+
- Remove or compress into a single contextual sentence tied to a decision or outcome.
119+
</enforcement>
120+
</gate>
121+
85122
<gate name="consistency_gate" type="BLOCKING">
86123
<description>Ensures documentation remains consistent</description>
87124
<requirements>
@@ -106,9 +143,10 @@
106143
<step order="2" mandatory="true">Complete content discovery with multiple search terms</step>
107144
<step order="3" mandatory="true">Read and analyze ALL discovered content</step>
108145
<step order="4" mandatory="true">Create validation report with findings</step>
109-
<step order="5" mandatory="true">Get user approval via ask_followup_question</step>
110-
<step order="6" conditional="true">Proceed with approved approach only</step>
111-
<step order="7" mandatory="true">Verify all changes maintain consistency</step>
146+
<step order="5" mandatory="true">Pass the Value Filter Gate and Obvious-UI Narration Blocker with documented evidence</step>
147+
<step order="6" mandatory="true">Get user approval via ask_followup_question</step>
148+
<step order="7" conditional="true">Proceed with approved approach only</step>
149+
<step order="8" mandatory="true">Verify all changes maintain consistency</step>
112150
</steps>
113151
<skip_consequence>
114152
Skipping ANY mandatory step results in:

‎.roomodes‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,20 @@ customModes:
4848
source: project
4949
- slug: documentation-writer
5050
name: 📖 Documentation Writer
51-
roleDefinition: You are a technical documentation writer for the Roo Code project. Your writing is direct, concise, and technical. You write for a developer audience and follow the instructions in the .roo/rules-docs/ directory to produce clear, high-signal Markdown documentation.
52-
whenToUse: Use this mode for creating or updating documentation in Markdown (.md, .mdx) files.
51+
roleDefinition: |-
52+
You are Roo Code, a documentation specialist who writes only what matters.
53+
Core behaviors:
54+
- Value-first: explain why before how; cut anything users can infer from the UI.
55+
- Bold, honest voice: direct, punchy, zero fluff; never fake hype.
56+
- Developer audience: precise, actionable, minimal steps.
57+
- Enforce the rules in .roo/rules-documentation-writer/ (writing style, value filter, screenshot policy).
58+
- Prefer consolidation over duplication; link to authoritative sources.
59+
whenToUse: |-
60+
Use this mode to create or refine technical docs (.md/.mdx) with a value-first approach.
61+
Triggers:
62+
- Pages drifting into UI narration or screen-by-screen walkthroughs
63+
- Need for concise "why it matters / what you can do" structure
64+
- Requests to add screenshots or restructure content for clarity
5365
description: Creates and maintains Roo technical docs.
5466
groups:
5567
- read

‎docs/roo-code-cloud/billing-subscriptions.mdx‎

Lines changed: 6 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -43,47 +43,24 @@ Open the Upgrade page (for non-subscribers):
4343

4444
### Step 2: Subscribe to Pro
4545

46-
The billing page displays:
47-
- Upgrade to Roo Code Cloud Pro card
48-
- Free for 14 days, then $20/month
49-
- Start Trial button
50-
51-
To subscribe:
52-
1. Click the **Start Trial** button
53-
2. You'll be redirected to Stripe's secure checkout
54-
3. Enter your payment information
55-
4. Complete the checkout process
46+
Click **Start Trial** to open Stripe checkout, complete payment, and begin your 14‑day trial (then $20/month).
5647

5748
### Step 3: Confirmation
5849

59-
After successful payment:
60-
- Your subscription status shows as **Active**
61-
- Full Roomote Control is automatically enabled
50+
After checkout:
51+
- Your plan shows as **Active**
52+
- Roomote Control is enabled immediately
6253
- You'll receive a confirmation email
63-
- Access your enhanced features immediately
64-
65-
The navigation changes from Upgrade to Billing, where you can view your active plan and access the Stripe customer portal.
54+
Manage your plan any time from the Billing page.
6655

6756
<img src="/img/billing-subscriptions/billing-subscriptions-2.png" alt="Billing page with active Pro plan and Manage Subscriptions" width="800" />
6857

6958
## Managing Your Subscription
7059

7160
### Subscription Portal
7261

73-
Access the Stripe customer portal to:
74-
- Update payment methods
75-
- Download invoices
76-
- View billing history
77-
- Change billing information
78-
79-
Click **Manage Subscription** on your billing page to access the portal.
80-
81-
### Subscription Status
62+
Click **Manage Subscription** to open Stripe's portal for payment methods, invoices, and billing details.
8263

83-
Your billing page displays:
84-
- **Active** - Subscription is current and features are enabled
85-
- **Canceled** - Subscription will end at period close
86-
- **Expired** - Subscription has ended, features disabled
8764

8865
### Cancellation
8966

‎docs/roo-code-cloud/dashboard.mdx‎

Lines changed: 4 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -50,51 +50,30 @@ The [Roomote Control](/roo-code-cloud/roomote-control) section at the top allows
5050
#### Tasks Section
5151
- **Toggle Task Sync** — Enable/disable monitoring for live updates from your IDE
5252

53-
The Tasks section below displays your task history with:
54-
- **Task description** - The prompt or request
55-
- **Timestamp** - When the task was created
56-
- **User** - Who created the task
57-
- **Mode** - Which AI mode was used (ask, code, architect, etc.)
58-
- **Status** - Complete, in progress, or failed
59-
- **Token count** - Total tokens consumed
60-
- **Cost** - Estimated cost for the task
53+
Use Task Sync to stream live updates and review task history; columns are self-explanatory.
6154

6255
### Usage Analytics Page
6356

6457
Access detailed usage metrics by clicking the **Usage** tab in the navigation bar or navigate directly to [app.roocode.com/usage](https://app.roocode.com/usage).
6558

6659
<img src="/img/dashboard/dashboard-1.png" alt="Usage Analytics page showing token usage graph and statistics" width="800" />
6760

68-
The Usage Analytics page provides:
69-
- **Interactive Graph** - Visual representation of token usage over time
70-
- **Time Range Selection** - View data for 24 hours, 7 days, 30 days, or 90 days
71-
- **Metrics Tabs** - Switch between Tokens, Tasks, and Cost views
72-
- **Summary Statistics**:
73-
- Total users
74-
- Activity count (e.g., "2/10" activities)
75-
- Total tokens consumed
76-
- Total estimated cost
61+
Track tokens, tasks, and estimated cost over selectable ranges (24h–90d) to monitor activity and spend.
7762

7863
### Upgrade Page (before subscribing)
7964

8065
Start your subscription from the **Upgrade** tab or navigate to [app.roocode.com/billing](https://app.roocode.com/billing).
8166

8267
<img src="/img/billing-subscriptions/billing-subscriptions-1.png" alt="Upgrade page showing Start Trial for Pro" width="800" />
8368

84-
This page shows:
85-
- Upgrade to Roo Code Cloud Pro card
86-
- Free for 14 days, then $20/month
87-
- Start Trial button
69+
Start a Pro trial from Upgrade.
8870

8971
### Billing Page (after subscribing)
9072

9173
After subscribing, the **Upgrade** tab is replaced by **Billing**. Manage your plan and access invoices at [app.roocode.com/billing](https://app.roocode.com/billing).
9274

9375
<img src="/img/billing-subscriptions/billing-subscriptions-2.png" alt="Billing page with active Pro plan and Manage Subscriptions" width="800" />
9476

95-
From this page you can:
96-
- View Pro Plan status and renewal date
97-
- Confirm $20/month amount
98-
- Open the Stripe customer portal via Manage Subscriptions
77+
Manage your plan and invoices from Billing.
9978

10079
See the [Billing & Subscriptions](/roo-code-cloud/billing-subscriptions) documentation for complete details.

‎docs/roo-code-cloud/login.mdx‎

Lines changed: 14 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -40,51 +40,27 @@ If you don't have an account yet, you have two options to create one:
4040

4141
### Option 1: Sign Up with GitHub or Google
4242

43-
The quickest way to create an account is using your existing GitHub or Google account:
44-
45-
1. From the sign-in page, click either the **GitHub** or **Google** button
46-
2. You'll be redirected to authenticate with your chosen provider
47-
3. After successful authentication, you'll see the Terms of Service and Privacy Policy agreement form:
43+
The quickest way: sign in with GitHub or Google, accept the Terms, and you're in.
4844

4945
<img src="/img/login/login-8.png" alt="Terms of Service agreement form after OAuth authentication" width="600" />
5046

51-
4. Review the Terms of Service and Privacy Policy
52-
5. Check the agreement box to accept the terms
53-
6. Click **Continue** to complete your account creation
54-
7. After account creation:
55-
- **If connecting from VS Code**: You'll see a confirmation popup (proceed to IDE Selection section below)
56-
- **If signing up directly at app.roocode.com**: You'll be redirected to your dashboard:
57-
47+
After creation:
48+
- If connecting from VS Code: you'll see a confirmation popup
49+
- If signing up directly at app.roocode.com: you'll land on your dashboard
50+
5851
<img src="/img/login/login-9.png" alt="Roo Code Cloud dashboard after direct signup" width="600" />
5952

6053
### Option 2: Sign Up with Email
6154

62-
Alternatively, create an account using your email address:
63-
64-
1. Click the **Sign up** link at the bottom of the sign-in page
55+
Alternatively, sign up with email: fill the form (email and password required), accept the Terms, and submit.
6556

6657
<img src="/img/login/login-7.png" alt="Roo Code Cloud signup form" width="600" />
6758

68-
2. Complete the signup form with:
69-
- **First name** (optional)
70-
- **Last name** (optional)
71-
- **Email address** (required)
72-
- **Password** (required)
73-
74-
3. Review the Terms of Service and Privacy Policy
75-
76-
4. Check the agreement box to accept the terms
77-
78-
5. Click the signup button to create your account
79-
80-
6. After account creation:
81-
- **If connecting from VS Code**: You'll see this confirmation popup:
82-
83-
<img src="/img/login/login-3.png" alt="Account creation confirmation popup" width="600" />
84-
85-
- **If signing up directly at app.roocode.com**: You'll be redirected to your dashboard:
86-
87-
<img src="/img/login/login-9.png" alt="Roo Code Cloud dashboard after direct signup" width="600" />
59+
After creation:
60+
- If connecting from VS Code: you'll see this confirmation popup:
61+
<img src="/img/login/login-3.png" alt="Account creation confirmation popup" width="600" />
62+
- If signing up directly at app.roocode.com: you'll land on your dashboard:
63+
<img src="/img/login/login-9.png" alt="Roo Code Cloud dashboard after direct signup" width="600" />
8864

8965
## IDE Selection
9066

@@ -100,14 +76,9 @@ Once authenticated, you'll be redirected back to your IDE where you'll see your
10076

10177
<img src="/img/dashboard/dashboard-3.png" alt="Successfully connected Roo Code Cloud account" width="600" />
10278

103-
This screen displays:
104-
- Your profile avatar and full name
105-
- Your connected account email address
106-
- **[Task Sync](/roo-code-cloud/task-sync)** toggle — Enabled automatically after connecting. Monitor tasks from any device via Roo Code Cloud.
107-
- **[Roomote Control](/roo-code-cloud/roomote-control)** toggle — Enable remote control (start/stop/interactive controls; Pro). Visible only when subscribed to Roo Code Cloud Pro; see [Billing & Subscriptions](/roo-code-cloud/billing-subscriptions#pro-plan-20month).
108-
- **Visit Roo Code Cloud** button - Opens the [web dashboard](/roo-code-cloud/dashboard) in your browser
109-
- **Log out** button - Disconnects your account from this IDE
110-
- **Done** button (top right) - Closes the Cloud panel and returns to normal Roo Code usage
79+
Key controls:
80+
- [Task Sync](/roo-code-cloud/task-sync) — enabled automatically after connecting
81+
- [Roomote Control](/roo-code-cloud/roomote-control) — Pro feature; see [Billing & Subscriptions](/roo-code-cloud/billing-subscriptions#pro-plan-20month)
11182

11283
Your Roo Code extension is now connected to Roo Code Cloud and ready to sync your data and enable collaboration features.
11384

0 commit comments

Comments
 (0)