Skip to content

Commit 4ce9a42

Browse files
committed
docs(tours): establish content standards and apply to foundational tours
- Audit "Using the Docs" and "Using Search" tours against new standards - Replace generic openers with benefit-driven language - Make all learn statements outcome-focused, not location-focused - Update skillz detail page heading to "You'll learn how to:" for consistency
1 parent b2fa6d2 commit 4ce9a42

File tree

3 files changed

+52
-50
lines changed

3 files changed

+52
-50
lines changed

apps/docs/src/pages/skillz.[id].vue

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -80,9 +80,6 @@
8080

8181
<template>
8282
<div class="min-h-[calc(100vh-64px)]">
83-
<!-- SkillzTour for testing -->
84-
<SkillzTour />
85-
8683
<!-- Not found state -->
8784
<div v-if="!tour" class="flex flex-col items-center justify-center py-16 px-8 text-center">
8885
<h1 class="m-0 mb-2 text-2xl">Skill Not Found</h1>
@@ -118,26 +115,31 @@
118115
class="border border-divider rounded-xl p-4 md:p-6"
119116
:class="settings.showBgGlass ? 'bg-glass-surface' : 'bg-surface'"
120117
>
121-
<div class="flex items-center gap-2 mb-4">
118+
<div class="flex items-center gap-2 mb-3">
122119
<SkillLevelBadge :level="tour.level" />
123120

124121
<SkillModeBadge :mode="tour.mode" />
125122

126123
<SkillMasteredBadge
127124
v-if="progress?.status === 'completed'"
128-
class="position-absolute top-2 right-2 md:top-4"
125+
class="position-absolute top-2 right-0 md:top-4"
129126
:size="breakpoints.mdAndDown.value ? 72 : 128"
130127
/>
131128
</div>
132129

130+
<div v-if="tour.categories.length" class="flex items-center gap-2 mb-4 text-xs text-on-surface-variant">
131+
<span class="font-medium">Category:</span>
132+
<SkillCategoryTags :categories="tour.categories" />
133+
</div>
134+
133135
<h1 class="text-2xl font-bold m-0 mb-3 text-on-surface">{{ tour.name }}</h1>
134136
<p class="text-base text-on-surface-variant m-0 mb-6 leading-relaxed md:pr-26">{{ tour.description }}</p>
135137

136138
<!-- <SkillMetadata class="mb-6" :skill="skill" /> -->
137139

138140
<!-- <SkillPrerequisites class="mb-6" :prerequisites="skill.prerequisites" variant="box" /> -->
139141

140-
<h2 class="text-base font-semibold m-0 mb-4 text-on-surface">What you'll learn</h2>
142+
<h2 class="text-base font-semibold m-0 mb-4 text-on-surface">You'll learn how to:</h2>
141143

142144
<ol class="list-none p-0 m-0" :class="{ 'mb-8': progress?.status !== 'completed' }">
143145
<li

apps/docs/src/skillz/tours/beginner/using-search/index.json

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,81 +7,81 @@
77
"categories": ["meta"],
88
"order": 1,
99
"prerequisites": [],
10-
"description": "Master the documentation search to find components, composables, and guides quickly.",
10+
"description": "Find exactly what you need in seconds with search, favorites, and keyboard shortcuts.",
1111
"minutes": 2,
1212
"startRoute": "/introduction/getting-started",
1313
"steps": [
1414
{
1515
"id": "search",
1616
"title": "Search Button",
17-
"task": "This is the search button. It opens the search panel where you can find components, composables, and guides.",
17+
"task": "Your fastest path to anything. Open search and start typing to find components, composables, and guides.",
1818
"hint": "Keyboard shortcut: Ctrl+K (or Cmd+K on Mac)",
19-
"learn": "Where to find search"
19+
"learn": "Access search from anywhere"
2020
},
2121
{
2222
"id": "search-input",
2323
"title": "Search Input",
24-
"task": "This is where you type your search query. Results update instantly as you type.",
24+
"task": "Type and watch. Results appear instantly as you type—no waiting, no Enter key needed.",
2525
"hint": "Arrow keys navigate results, Enter selects.",
26-
"learn": "Where to type search queries",
26+
"learn": "Get instant results as you type",
2727
"placement": "bottom"
2828
},
2929
{
3030
"id": "search-results",
3131
"title": "Search Results",
32-
"task": "Results are grouped by category: Components, Composables, Guides, and more. The best matches appear first.",
32+
"task": "Organized by type. Components, composables, guides—scroll or arrow through to find what you need.",
3333
"hint": "",
34-
"learn": "How search results are organized"
34+
"learn": "Navigate categorized search results"
3535
},
3636
{
3737
"id": "search-favorite",
3838
"title": "Favorite Results",
39-
"task": "The star icon adds a result to your favorites. Favorites appear at the top when search is empty for quick access.",
39+
"task": "Bookmark your go-tos. Star anything you use often and it'll be waiting at the top next time.",
4040
"hint": "",
41-
"learn": "What the favorite button does",
41+
"learn": "Quick-access your most-used pages",
4242
"placement": "left",
4343
"placementMobile": "bottom"
4444
},
4545
{
4646
"id": "search-ask-ai",
4747
"title": "Ask AI",
48-
"task": "This button navigates to the page and asks AI about the topic. Great for getting a quick overview.",
48+
"task": "Skip the reading. Hit this to jump straight to a page and ask AI to explain it.",
4949
"hint": "",
50-
"learn": "What the Ask AI button does",
50+
"learn": "Get AI explanations for any topic",
5151
"placement": "left",
5252
"placementMobile": "bottom"
5353
},
5454
{
5555
"id": "search-dismiss",
5656
"title": "Dismiss Results",
57-
"task": "The X icon hides a result for the current session. Useful for filtering out irrelevant matches.",
57+
"task": "Too many results? Dismiss irrelevant matches and focus on what matters.",
5858
"hint": "",
59-
"learn": "What the dismiss button does",
59+
"learn": "Filter out noise from search results",
6060
"placement": "left",
6161
"placementMobile": "bottom"
6262
},
6363
{
6464
"id": "search-history",
6565
"title": "Search History",
66-
"task": "Recent searches appear here when the search field is empty. History persists between sessions.",
66+
"task": "Pick up where you left off. Recent searches stick around between sessions.",
6767
"hint": "",
68-
"learn": "Where to find search history",
68+
"learn": "Resume previous searches instantly",
6969
"placement": "bottom"
7070
},
7171
{
7272
"id": "search-favorited",
7373
"title": "Favorited!",
7474
"task": "We just added Tabs to your favorites. Notice it now appears at the top for quick access anytime you open search.",
7575
"hint": "",
76-
"learn": "How favorites work in practice",
76+
"learn": "See favorites in action",
7777
"placement": "bottom"
7878
},
7979
{
8080
"id": "conclusion",
81-
"title": "You're a Search Pro!",
82-
"task": "That covers the search features. Use Ctrl+K anytime to quickly find what you need.",
81+
"title": "That's Search",
82+
"task": "Hit Ctrl+K whenever you need something—it's the fastest way around the docs.",
8383
"hint": "",
84-
"learn": "Ready to search like a pro",
84+
"learn": "Search like a power user",
8585
"noActivator": true
8686
}
8787
]

apps/docs/src/skillz/tours/beginner/using-the-docs/index.json

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,97 +7,97 @@
77
"categories": ["meta"],
88
"order": 0,
99
"prerequisites": [],
10-
"description": "A quick tour of the Vuetify0 documentation site.",
10+
"description": "Learn where everything lives and how to get the most out of the docs.",
1111
"minutes": 3,
1212
"startRoute": "/introduction/why-vuetify0",
1313
"steps": [
1414
{
1515
"id": "search",
1616
"title": "Search",
17-
"task": "This is the search. It finds components, composables, and guides across the entire documentation.",
17+
"task": "Find anything instantly. Search covers components, composables, guides—even deep API references.",
1818
"hint": "",
19-
"learn": "Where to find the search"
19+
"learn": "Instantly locate any component or guide"
2020
},
2121
{
2222
"id": "navigation",
2323
"title": "Navigation",
24-
"task": "This is the main navigation sidebar. It organizes all documentation into sections: components, composables, guides, and more.",
24+
"task": "Your map to everything. Browse by category or expand sections to explore what's available.",
2525
"hint": "",
26-
"learn": "Where to find the navigation sidebar",
26+
"learn": "Navigate the full documentation structure",
2727
"placement": "right"
2828
},
2929
{
3030
"id": "toc",
3131
"title": "Table of Contents",
32-
"task": "The TOC shows all headings on the current page. Click any heading to jump directly to that section.",
33-
"hint": "Table of Contents is not available on mobile devices.",
34-
"learn": "How to navigate within a page",
32+
"task": "Jump to any section. Click a heading to skip straight there—no scrolling required.",
33+
"hint": "Not available on mobile devices.",
34+
"learn": "Jump directly to any section on a page",
3535
"placement": "left",
3636
"skipOnMobile": true
3737
},
3838
{
3939
"id": "page-actions",
4040
"title": "Page Actions",
41-
"task": "Every page has quick actions: edit on GitHub, report bugs, view source code, and copy as markdown.",
41+
"task": "Spot something wrong? Edit it on GitHub, report it, or grab the source—directly from any page.",
4242
"hint": "",
43-
"learn": "How to contribute and report issues"
43+
"learn": "Report issues or contribute improvements"
4444
},
4545
{
4646
"id": "page-metadata",
4747
"title": "Page Metadata",
48-
"task": "Metadata shows the skill level, test coverage, performance tier, and last update date for each feature.",
48+
"task": "Know what you're getting into. Skill level, test coverage, and performance tier—at a glance.",
4949
"hint": "",
50-
"learn": "How to assess feature quality and complexity",
50+
"learn": "Assess feature complexity before diving in",
5151
"placementMobile": "top"
5252
},
5353
{
5454
"id": "ask-ai",
5555
"title": "Ask AI",
56-
"task": "This is Ask AI. It's a context-aware assistant that knows the content of the current page and can answer your questions.",
56+
"task": "Stuck? Ask AI knows this page inside out. Ask anything and get an answer in seconds.",
5757
"hint": "",
58-
"learn": "Where to find the AI assistant",
58+
"learn": "Get instant answers without leaving the page",
5959
"placement": "top"
6060
},
6161
{
6262
"id": "ask-ai-panel",
6363
"title": "Ask AI Panel",
64-
"task": "Asking a question opens up the Ask AI panel. Here you can see the conversation history and interact with the assistant.",
64+
"task": "Your conversation lives here. Scroll back through history or pick up where you left off.",
6565
"hint": "",
66-
"learn": "How to use the Ask AI panel",
66+
"learn": "Continue conversations across sessions",
6767
"placement": "left",
6868
"placementMobile": "top"
6969
},
7070
{
7171
"id": "ask-ai-features",
7272
"title": "Conversation Tools",
73-
"task": "The toolbar has options to save your conversation to Vuetify Bin, copy it, or reset and start fresh.",
73+
"task": "Save, copy, or start fresh. Your AI conversations can be exported to Vuetify Bin for later.",
7474
"hint": "",
75-
"learn": "What the Ask AI toolbar does",
75+
"learn": "Save and export AI conversations",
7676
"placement": "left",
7777
"placementMobile": "bottom"
7878
},
7979
{
8080
"id": "settings",
8181
"title": "Settings",
82-
"task": "This is the settings panel. It has theme options, layout preferences, and content filters.",
82+
"task": "Make it yours. Toggle themes, adjust layout, and filter content to match how you work.",
8383
"hint": "",
84-
"learn": "Where to find settings"
84+
"learn": "Customize the docs to your preferences"
8585
},
8686
{
8787
"id": "skill-level",
8888
"title": "Skill Levels",
89-
"task": "These filters control which content appears in the navigation. Beginner shows fundamentals, Intermediate adds detail, and Advanced shows everything.",
89+
"task": "Show what matters. Beginner sticks to fundamentals. Advanced unlocks everything.",
9090
"hint": "",
91-
"learn": "What skill level filters do",
91+
"learn": "Filter content to match your experience",
9292
"placement": "left",
9393
"placementMobile": "top"
9494
},
9595
{
9696
"id": "complete",
97-
"title": "Tour Complete!",
98-
"task": "That's it for the tour! You're now ready to explore the Vuetify0 documentation like a pro.",
97+
"title": "Tour Complete",
98+
"task": "You've got the lay of the land. Go explore—or dive into another tour when you're ready.",
9999
"hint": "",
100-
"learn": "You're all set!"
100+
"learn": "Confidently navigate the entire docs site"
101101
}
102102
]
103103
}

0 commit comments

Comments
 (0)