Skip to content

Commit f99e741

Browse files
madebyankurmadebyankur
authored
Merge branch 'main' into ui/styling-updates
2 parents b29197f + ffe9c35 commit f99e741

File tree

203 files changed

+6052
-3584
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

203 files changed

+6052
-3584
lines changed

‎.claude/skills/writing-quickstarts/SKILL.md‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
---
2+
name: writing-quickstarts
3+
description: Guides technical writers through creating Auth0 QuickStart guides that address known usability patterns. Use when writing new QuickStarts, improving existing integration guides, clarifying navigation, structuring prerequisites, or simplifying external service setup.
4+
---
5+
6+
# Writing Auth0 QuickStarts
7+
8+
Create QuickStart guides that help users integrate Auth0 authentication successfully.
9+
10+
Refer to the `writing-auth0-docs` skill for comprehensive style guide information including voice, tone, terminology, and formatting conventions.
11+
12+
## Known usability patterns
13+
14+
QuickStart users consistently struggle with:
15+
- **Dashboard navigation**: Multiple Settings pages in the Auth0 Dashboard with similar names cause confusion
16+
- **Setup flow distinction**: Users treat setup steps as part of main workflow, not separate preparation
17+
- **External service complexity**: Third-party configurations involve platform switching and unfamiliar interfaces
18+
- **Resource relationships**: Similar Auth0 resources need explicit differentiation
19+
- **Missing context**: Users need to understand why each step matters, not just how
20+
21+
## QuickStart structure
22+
23+
QuickStarts are guides that help readers complete a task efficiently. Structure every QuickStart in three phases:
24+
- **Setup phase**: Dashboard configuration and resource creation
25+
- **Integration phase**: Code implementation and configuration
26+
- **Verification phase**: Testing and troubleshooting
27+
28+
Name sections appropriately for your context while maintaining this logical flow.
29+
30+
## Start with goals and prerequisites
31+
32+
Begin every QuickStart with a clear goal explaining what the developer will achieve.
33+
34+
List all prerequisites:
35+
- Programming language familiarity
36+
- Required concepts
37+
- Installed developer tools
38+
- Required user accounts
39+
- Existing configuration needs
40+
41+
Make each step clear about why it needs to be followed.
42+
43+
## Setup phase
44+
45+
Provide the same level of detail as your integration section. Users don't mentally separate these phases.
46+
47+
### Navigation must be explicit
48+
49+
Always specify which Settings page in the Auth0 Dashboard you mean. The Dashboard contains multiple Settings pages:
50+
- Application Settings (specific to each application)
51+
- Tenant Settings (account-wide settings)
52+
- API Settings (specific to each API)
53+
54+
Never write "Go to Settings" without qualification. Always provide full navigation paths with dashboard links.
55+
56+
### Structure each resource setup
57+
58+
For each resource:
59+
1. Purpose statement - why this resource exists and how it's used
60+
2. Navigation - exact path with dashboard link
61+
3. Configuration steps - numbered, sequential instructions
62+
4. Field explanations - what each setting does and why it matters
63+
5. Checkpoint - confirmation of correct state via callout
64+
6. Forward reference - how this connects to integration
65+
66+
### Writing steps effectively
67+
68+
- Tell users what the outcome should be before describing the behavior
69+
- List actions in the order they need to happen
70+
- Be direct and concise for introductory text
71+
72+
## Integration phase
73+
74+
### Start with environment configuration
75+
76+
Always begin with environment setup showing exact format. Explain what each value represents and where it came from.
77+
78+
### Include complete examples
79+
80+
Examples are crucial - many developers copy and paste. Ensure:
81+
- Each step has an example
82+
- Examples can be copied, pasted, and executed
83+
- Placeholders are clearly highlighted when values need replacement
84+
- Downloaded projects match examples exactly (naming conventions, structure, code location)
85+
86+
### Code quality requirements
87+
88+
- Include all imports
89+
- Use realistic, descriptive variable names
90+
- Comment Auth0-specific parts
91+
- Connect each parameter back to dashboard configuration with inline comments
92+
- Show complete, runnable code - not snippets requiring assembly
93+
94+
### Explain configuration parameters
95+
96+
For each parameter describe:
97+
- What it is
98+
- Why it's needed
99+
- What value to use
100+
- How it connects to dashboard configuration
101+
102+
### Maintain consistent terminology
103+
104+
Choose one term for each concept throughout. Don't alternate between synonyms.
105+
106+
## Verification phase
107+
108+
### Testing and troubleshooting
109+
110+
- Number each verification step showing exactly what should happen
111+
- Use accordions when you have four or more common errors
112+
- For each error: show the message, explain the cause, provide resolution steps
113+
- Explicitly state what indicators show successful integration
114+
115+
### Notes and warnings
116+
117+
- **Notes**: General information that would be nice to know
118+
- **Warnings**: Information that may cause failure if not followed
119+
- Place warnings exactly where the user needs to perform the related action
120+
121+
## External service setup pattern
122+
123+
Third-party configurations require platform switching and unfamiliar interfaces. Use a clear two-part structure.
124+
125+
### External service configuration
126+
- Set context explicitly - state you're leaving Auth0 and entering another platform
127+
- Tell users to keep both tabs open
128+
- Number steps clearly with descriptive headers for each phase
129+
- Provide exact values with placeholder replacement instructions
130+
- Add checkpoints confirming what credentials or settings should exist
131+
132+
### Auth0 connection configuration
133+
- Bridge back explicitly - state you're returning to Auth0 Dashboard
134+
- Show exactly where external credentials go in Auth0
135+
- Show how to activate the connection for the application
136+
- Provide test procedure with common error resolutions
137+
138+
## Clarify complex relationships
139+
140+
When users must create multiple related resources:
141+
- Use callout upfront to indicate which tech stacks require these steps
142+
- Provide skip-ahead link for others
143+
- Create clear contrast: what each represents, how they differ, why both needed, how they work together
144+
- Show relationship visually if possible
145+
- Show exactly how each resource appears in code
146+
147+
## Break tasks into steps and sub-tasks
148+
149+
QuickStarts can be read in parts or as a whole. Use clear hierarchy.
150+
151+
When describing a feature, answer:
152+
- Who typically does the task?
153+
- What is the goal?
154+
- Why is the task needed?
155+
- When and where in the workflow should it happen?
156+
- Does it deserve its own section or fall under a larger task?
157+
158+
Don't add too much conceptual information in step descriptions. Link to concept documentation instead.
159+
160+
Break out reference sections (tables, lists, best practices, troubleshooting) into separate documents when they could be reused.
161+
162+
## Headings
163+
164+
Use sentence case - only capitalize first word and proper nouns or Auth0 product names.
165+
166+
Use simple tense, not progressive or gerund forms.
167+
168+
Use task-oriented titles describing performance goals, not Auth0-specific feature names.
169+
170+
## Content patterns
171+
172+
- **Callouts**: Supplementary information or warnings for critical issues
173+
- **Cards**: "Find your X" helpers, concept clarifications, related information
174+
- **Accordions**: Lists of four or more items (troubleshooting, optional features, detailed references)
175+
- **Tabs**: Same result through different paths (Dashboard vs API, different providers/frameworks)
176+
- **Tooltips**: First mention of Auth0 or CIAM terms, linking to glossary
177+
178+
## Content organization checklist
179+
180+
Before publishing verify:
181+
182+
**Structure**
183+
- Setup matches integration detail level
184+
- Steps numbered sequentially
185+
- Purpose stated for each section
186+
- Tasks broken into appropriate sub-tasks
187+
- Minimal conceptual information (linked to concept docs)
188+
189+
**Navigation**
190+
- Specific Dashboard Settings page identified (Application, Tenant, or API)
191+
- Dashboard links provided
192+
- Full paths shown
193+
- Device-agnostic directions ("select" not "click", avoid "scroll")
194+
195+
**Explanations**
196+
- Setup steps explain why needed
197+
- Format-sensitive values have examples
198+
- Resource relationships clarified
199+
- Glossary terms have tooltips
200+
201+
**Code**
202+
- Examples complete and runnable
203+
- Can be copied, pasted, and executed
204+
- Placeholders clearly highlighted
205+
- Auth0 parts commented
206+
- Variable names descriptive
207+
- Downloaded projects match examples exactly
208+
209+
**Verification**
210+
- Checkpoints after major steps
211+
- Testing instructions provided
212+
- Troubleshooting organized (accordions for 4+ items)
213+
- Success criteria defined
214+
- Warnings placed exactly where needed
215+
216+
**External integrations**
217+
- Two-part structure clear
218+
- Platform switching explicit
219+
- Exact configuration values
220+
- Verification included
221+
222+
## Common mistakes
223+
224+
- **Vague navigation**: Always specify which Settings page (Application, Tenant, or API) and provide link
225+
- **Assumed knowledge**: Never assume users know where to find Auth0 resources
226+
- **Missing purpose**: Every configuration step needs a "why"
227+
- **Inconsistent terms**: Pick one name per concept and stick with it
228+
- **Tech stack assumptions**: Note which instructions vary by stack
229+
- **Generic link text**: Make link titles scannable and descriptive
230+
- **Wrong verb/noun forms**: "Log in" (verb) vs "login" (noun), "set up" (verb) vs "setup" (noun)
231+
- **Wrong heading case**: Use sentence case, not title case
232+
- **Progressive tense in headings**: Use simple tense
233+
- **Expectations last**: Tell users what will happen before what to do
234+
- **Too much concept**: Link to explanatory documentation instead
235+
- **Reference sections inline**: Break out reusable reference information

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,4 +62,4 @@ pnpm add -g mint
6262
- **Check accessibility**: `mint a11y`
6363
- **Custom port**: `mint dev --port 3333`
6464

65-
For more details, see the [Mintlify CLI documentation](https://mintlify.com/docs/installation).
65+
For more details, see the [Mintlify CLI documentation](https://mintlify.com/docs/installation).

‎auth4genai/.vale.ini‎

Lines changed: 117 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,122 @@
1+
; Vale configuration for Mintlify docs.
2+
; Mintlify CI will pick this up if enabled:
3+
; https://www.mintlify.com/docs/deploy/ci
4+
;
5+
; Keep this file under version control and evolve it with the docs:
6+
; https://www.mintlify.com/guides/maintenance
7+
;
8+
; Vale config reference:
9+
; https://vale.sh/docs
10+
;
11+
; MDX support:
12+
; - Vale 3.13+ treats .mdx as a first class format.
13+
; - MDX parsing is handled by the external mdx2vast CLI, which must be
14+
; installed and available on $PATH:
15+
; npm install -g mdx2vast
16+
;
17+
; When Vale flags something that is actually OK:
18+
; - If it is project-wide (for example a product name), add it to:
19+
; .vale/styles/config/ignore/authdocs.txt
20+
; - If it is a systematic branding issue, add a swap to:
21+
; .vale/styles/AuthDocs/Brands.yml
22+
; - Only use {/* vale off */} / {/* vale on */} for
23+
; narrow, one-off cases (quotes, unusual examples).
24+
25+
StylesPath = .vale/styles
26+
27+
; Only report error-level issues. Suggestions and warnings are suppressed
28+
; entirely so devs are not blocked on minor style nits.
129
MinAlertLevel = error
230

3-
[formats]
4-
mdx = md
31+
; Scopes to ignore completely. These are either:
32+
; - Already covered by other tooling, or
33+
; - Places where language checks are too noisy or fragile
34+
; (inline code, URLs, links, images).
35+
; Note: 'code' is handled by SkippedScopes below for block-level code.
36+
IgnoredScopes = tt, img, url, a
37+
38+
; Skip entire blocks that are not prose. This keeps Vale out of
39+
; style/script tags, <pre> blocks, code fences, and figures.
40+
SkippedScopes = script, style, pre, figure, code
41+
42+
; Optional checks developers may enable locally:
43+
; vale.Annotations = YES
544

645
[*.mdx]
7-
BasedOnStyles = Vale
8-
Vale.Terms = NO
46+
; Base on Vale's core rules plus our custom AuthDocs style:
47+
; https://vale.sh/docs/getting-started/configuration/#basedonstyles
48+
BasedOnStyles = Vale, AuthDocs
49+
50+
; Keep helpful core rules for terminology consistency and
51+
; repeated word detection across the docs.
52+
Vale.Terms = YES
53+
Vale.Repetition = YES
54+
55+
; Replace the built-in spelling rule with a custom one that knows about our
56+
; domain-specific vocabulary:
57+
; https://vale.sh/docs/checks/spelling
58+
; Turning Vale.Spelling off here avoids double reporting issues that our
59+
; AuthDocs.Spelling rule already handles with an ignore list.
960
Vale.Spelling = NO
10-
Vale.Repetition = NO
61+
AuthDocs.Spelling = YES
62+
63+
; Substitution rule for brand capitalization and common typos:
64+
; https://vale.sh/docs/checks/substitution
65+
; Keep this focused so that automated fixes remain predictable.
66+
AuthDocs.Brands = YES
67+
68+
[*.md]
69+
; Apply the same style stack to plain Markdown files so behavior
70+
; is consistent across .md and .mdx content.
71+
BasedOnStyles = Vale, AuthDocs
72+
73+
; Keep behavior consistent with MDX files.
74+
Vale.Terms = YES
75+
Vale.Repetition = YES
76+
77+
; Use the same custom spelling + brand rules as MDX.
78+
Vale.Spelling = NO
79+
AuthDocs.Spelling = YES
80+
AuthDocs.Brands = YES
81+
82+
; Snippets and code-heavy examples: disable brand rules.
83+
; These files are mostly inline code and copied examples where
84+
; strict brand enforcement would generate a lot of noise.
85+
[snippets/**/*.mdx]
86+
AuthDocs.Brands = NO
87+
88+
; Component demo content: disable spelling and brand rules.
89+
; This page is primarily example copy used to exercise UI components,
90+
; not user-facing documentation.
91+
[components.mdx]
92+
AuthDocs.Brands = NO
93+
AuthDocs.Spelling = NO
94+
95+
; Sample app index pages: disable brands.
96+
; Mostly links, titles, and names where strict enforcement over-triggers.
97+
[mcp/sample-apps.mdx]
98+
AuthDocs.Brands = NO
99+
100+
[sample-apps.mdx]
101+
AuthDocs.Brands = NO
102+
103+
; GitHub integration page: disable brands.
104+
; Contains github in URLs and domain-like strings where strict brand
105+
; correction would generate noise.
106+
[integrations/github.mdx]
107+
AuthDocs.Brands = NO
108+
109+
; GitHub how-to snippet files: disable brands.
110+
; Contain lowercase github in text and URLs.
111+
[snippets/how-tos/github/**/*.mdx]
112+
AuthDocs.Brands = NO
113+
114+
; SDK documentation pages: disable brands.
115+
; Contain GitHub sample repository URLs.
116+
[sdks/**/*.mdx]
117+
AuthDocs.Brands = NO
118+
119+
; Overview and hub pages: disable brands.
120+
; Mostly cards and links that aggregate other content.
121+
[how-tos/overview.mdx]
122+
AuthDocs.Brands = NO

0 commit comments

Comments
 (0)