Skip to content

Commit 11df493

Browse files
btiernayclaude
btiernay
and
claude
committed
Add Auth0 Docs Style Guide skill for Claude Code
Introduces a comprehensive writing-auth0-docs skill that enforces Auth0 documentation standards when authoring new content or fixing style violations. The skill provides quick reference to style guidelines covering documentation types, voice/tone, grammar, formatting, terminology, and translation readiness. The skill includes: - Quick reference table for common authoring tasks - Complete Auth0 Docs Style Guide reference files - Guidelines for documentation types, structure, and user focus - Writing mechanics (voice, tense, grammar, punctuation) - Formatting conventions (tables, notes, callouts, code blocks) - Terminology and capitalization rules - Translation-ready writing practices - Compliance and operational policies This skill ensures consistent, user-focused, and translation-ready documentation across the Auth0 docs-v2 repository. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent b5e38e9 commit 11df493

12 files changed

+1424
-0
lines changed

‎.claude/skills/writing-auth0-docs/SKILL.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
name: writing-auth0-docs
3+
description: Use when authoring new documentation or fixing style/formatting violations in Auth0 docs-v2 repository - enforces Auth0 Docs Style Guide for terminology, voice/tone, admonitions, placeholders, capitalization, and translation readiness (not for reading/understanding docs)
4+
---
5+
6+
# Auth0 Docs Authoring Skill
7+
8+
**Scope:** This skill applies ONLY to the Auth0 docs-v2 repository.
9+
10+
Use this skill when actively authoring new Auth0/Okta documentation or fixing style violations in this repository to ensure content aligns with the Auth0 Docs Style Guide.
11+
12+
## When NOT to Use This Skill
13+
14+
**Do NOT load for:**
15+
- Reading existing docs to understand Auth0 features or APIs
16+
- Searching docs for information
17+
- General discussion about documentation content
18+
- Code implementation (even if docs-related)
19+
- Navigating or exploring the docs repository
20+
21+
**Only load when actively authoring or correcting documentation style/structure.**
22+
23+
## Quick Reference
24+
25+
| Task | Reference File |
26+
|------|----------------|
27+
| Choose doc type (concept/guide/reference) | [documentation-types.md](reference/documentation-types.md), [document-structure.md](reference/document-structure.md) |
28+
| Voice, tone, user focus | [focus-on-the-user.md](reference/focus-on-the-user.md) |
29+
| Grammar, tense, pronouns, punctuation | [writing-mechanics.md](reference/writing-mechanics.md) |
30+
| Tables, notes, callouts, code blocks | [formatting.md](reference/formatting.md) |
31+
| Terminology, capitalization, UI wording | [word-lists.md](reference/word-lists.md) |
32+
| Links, images, code, placeholders, UI text | [other-conventions.md](reference/other-conventions.md) |
33+
| Translation-ready writing | [writing-for-translation.md](reference/writing-for-translation.md) |
34+
| Deprecations, compliance, Early Access | [operational-policies-and-regulatory-articles.md](reference/operational-policies-and-regulatory-articles.md) |
35+
| Overview and external resources | [auth0-docs-style-guide.md](reference/auth0-docs-style-guide.md), [references-and-resources.md](reference/references-and-resources.md) |
36+
37+
## Workflow
38+
39+
**Before drafting:**
40+
- Choose doc type (concept/guide/reference) and title accordingly
41+
- Plan headings for scannability, focus on one primary topic
42+
- Note required terminology and compliance constraints
43+
44+
**While writing:**
45+
- Voice/tone: Clear, approachable, user-focused
46+
- Grammar: Present tense, active voice, imperative mood for instructions
47+
- Headings: Sentence case (not title case)
48+
- Language: Inclusive, accessible, avoid idioms/jargon
49+
- Terminology: Use Word Lists for Auth0 features, capitalization
50+
- Formatting: Follow rules for links, images, alt text, code blocks
51+
52+
**For translation readiness:**
53+
- Short, unambiguous sentences
54+
- Avoid and/or, (s) plurals, idiomatic phrasal verbs
55+
- Define abbreviations on first use
56+
- Reuse existing phrasing for translation memory
57+
58+
**For compliance/regulatory:**
59+
- Legal/Security/Compliance teams are source of truth
60+
- Follow structure for Early Access, Beta, deprecation notices
61+
- Include required dates, replacement features, migration links
62+
63+
**When in doubt:** Prefer the most specific reference (Word Lists for terminology, Writing for Translation for international readers, Other Conventions for UI text/links). Apply guidance concisely without quoting verbatim.
64+
65+
## Common Mistakes
66+
67+
| Mistake | Fix |
68+
|---------|-----|
69+
| Title case for headings | Use sentence case (only first word capitalized) |
70+
| Warning for Enterprise plan restrictions | Use Callout with `icon="file-lines" color="#0EA5E9"` |
71+
| Placeholder format `{{VAR}}` | Use `YOUR_SOMETHING` or `<something-id>` conventions |
72+
| Passive voice in instructions | Use active voice and imperative mood |
73+
| Using and/or or (s) for plurals | Write out both options or rephrase for clarity |
74+
| Generic "click here" links | Use descriptive link text |
75+
| Missing alt text for images | Provide specific, descriptive alt text |

‎.claude/skills/writing-auth0-docs/reference/auth0-docs-style-guide.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Auth0 Docs Style Guide
2+
3+
### Overview
4+
5+
This style guide covers terminology and content specific to Auth0, along with some comments on common writing issues. It is a house style guide, not a complete set of writing guidelines or a statement that our decisions are objectively correct.
6+
7+
Like most style guides, our style guide aims to improve the consistency of our documentation, but this guide is a living document, so it changes over time. When it changes, we may not always change previously published documentation to match. When in doubt, follow this guide rather than imitating existing, potentially outdated documents.
8+
9+
Some of these guidelines are adapted and remixed from [Google’s Developer Documentation Style Guide](https://developers.google.com/style) and [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/), per Creative Commons License.
10+
11+
To learn more about Auth0 Branding, see the [Auth0 Brand Guide](https://docs.google.com/presentation/d/1fezeXGrDyK7AtRmTA13ivD-xFnxRXo5khkkL7tx6Cs8/edit?usp=sharing).
12+
13+
## Style standards
14+
15+
In general, we use American English according to the standards described in the [Associated Press's (AP) Stylebook](https://www.apstylebook.com/). For general software-industry styles and terminology, see the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
16+
17+
That said, we'd rather you submit good information that doesn't conform to this guide than no information at all. Auth0’s technical writers are always happy to help you with stylistic concerns—without judgement.
18+
19+
## Accessibility and inclusivity
20+
21+
We write our documentation with accessibility and inclusivity in mind. Many of the choices we have documented in this guide were made with the intent of meeting [Web Content Accessibility Guidelines (WCAG) requirements](https://www.w3.org/WAI/standards-guidelines/wcag/). In addition, we use inclusive language throughout our docs to ensure our documentation is accessible and welcoming to all readers.

‎.claude/skills/writing-auth0-docs/reference/document-structure.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Document Structure
2+
3+
Document structure describes the organization of a document into graphical elements, such as sections, paragraphs, and sentences.
4+
5+
### Headings
6+
7+
Use short headings to group related paragraphs and clearly describe the sections. Good headings provide an outline of the content.
8+
9+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
10+
| --- | --- |
11+
| Use clear section headings to organize content logically | Avoid walls of text without clear heading structure |
12+
13+
### Verb forms
14+
15+
In headings with verbs, avoid the infinitive and gerund form and use the simple tense.
16+
17+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
18+
| --- | --- |
19+
| Connect a custom database | How to connect a custom database<br>Connecting a custom database |
20+
| Assign and change users | Assigning and changing users |
21+
22+
### Ambiguity
23+
24+
Include all words that you need to clarify what is in the section.
25+
26+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
27+
| --- | --- |
28+
| IP routing protocols | Routing protocols |
29+
| Use scripts to monitor user activity | Monitoring scripts |
30+
| Suggestions for setting up user metadata | Things to consider |
31+
| Reverse proxy server requirements | Requirements |
32+
33+
### Capitalization
34+
35+
Use title case for document titles; capitalize every word except articles (“a”, “an”, “the”), coordinating conjunctions (“and”, “but”, “or”, “nor”, “for”, “so”, and “yet”), and [prepositions](https://grammarist.com/grammar/prepositions) fewer than four letters long. Capitalize the second part of hyphenated major words (for example, Self-Report rather than Self-report) unless the first element is a prefix like “pre-”, “post-”, or “anti-” (for example, Post-game rather than Post-Game).
36+
37+
Use sentence case for headings. Capitalize only the first word of each heading (unless it is case-sensitive) and all proper nouns.
38+
39+
### Singular vs. plural forms
40+
41+
Use the plural form of nouns in headings unless the singular form is obviously required.
42+
43+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
44+
| --- | --- |
45+
| Restore backup files | Restoring a backup file |
46+
| Create Delegated Admin Applications | Create a Delegated Admin Application |
47+
| Install the Delegated Admin Extension | Installing the Delegated Admin Extension |
48+
49+
## Content
50+
51+
### Introductory text
52+
53+
In the first few sentences, try to describe who, what, and when. Include an example if possible.
54+
55+
Avoid using phrases like:
56+
57+
- This guide will show...
58+
- This tutorial shows you...
59+
- This article describes...
60+
- This document...
61+
- Auth0 offers...
62+
63+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
64+
| --- | --- |
65+
| As a tenant administrator, use the Delegated Admin Extension to allow a select group of your users to access the Users section of the Auth0 Dashboard. | This guide will show you how to install the Delegated Admin Extension, which allows you to expose the Users section of the Auth0 Dashboard to a select group of users without allowing them access to the rest of the Dashboard. |
66+
| If you are responsible for managing your build system, use the Deploy CLI tool to manage a configuration repository for each environment and deploy them using the command line. | Auth0 offers a Deploy CLI tool that we recommend you incorporate into your build system. |
67+
68+
### Body text
69+
70+
In general, keep paragraphs short for internet reading.
71+
72+
Also, consider the following:
73+
74+
- Subheadings are not independent statements. Repeat the information from the subheading in the paragraph.
75+
- When mentioning several elements, use lists.
76+
- Avoid abbreviations. Use “for example” instead of “e.g.” Do not use “etc”.
77+
- Refer to the developer's customer as the "user".
78+
- If you need to use the name of a fictional company, use "ExampleCo".
79+
- Don't pre-announce anything. Avoid “currently” or “available in an upcoming release”.
80+
- Avoid overusing adjectives or adverbs. Never use more than two in a sentence.
81+
82+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
83+
| --- | --- |
84+
| To enable authentication in your application, use the OpenID Connect (OIDC) middleware. | The easiest way to enable authentication with Auth0 in your application is to use the OpenID Connect middleware. |
85+
| Once a user has logged in, you can go to `/Account/Claims` to see these claims. | Once a user has signed in, you can simply go to `/Account/Claims` to see these claims. |
86+
87+
### Steps
88+
89+
Use the imperative form for steps.
90+
91+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
92+
| --- | --- |
93+
| Save authentication data. | Authentication data should be saved. |
94+
| Set user email preferences. | Email preferences can be set. |
95+
96+
If an action is required, use "must".
97+
98+
If an action is available, use "can".
99+
100+
If an action is optional, use "may".
101+
102+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
103+
| --- | --- |
104+
| To limit access to your resources, you must use scopes. | To limit access to your resources, you should use scopes. |
105+
| To limit access to your resources, use scopes. | You might want to use scopes to limit access to your resources. |
106+
| You may want to create more access roles. | Creating more access roles is possible. |
107+
108+
Use "select" when referring to text links in a webpage or UI components. Remember that the UI may be rendered differently on different devices
109+
110+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
111+
| --- | --- |
112+
| Select **Save**. | Click **Save**. |
113+
| Select **Go to Settings** to access the settings section. | Click **Go to Settings** to access the settings section. |
114+
115+
Depending on the situation, the reader can "gain access", "grant access", or "allow access".
116+
117+
## Nesting
118+
119+
Avoid deep nesting of document structure. Three levels of headings are usually enough.
120+
121+
The same applies to lists: avoid lists that are nested too deeply, in most cases, two levels should be enough.

‎.claude/skills/writing-auth0-docs/reference/documentation-types.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Documentation Types
2+
3+
Documentation is read by developers in different ways, depending on the situation. Good documentation supports the situation and helps the developer find the information needed to complete the task at hand.
4+
5+
In support of this, there are three documentation types:
6+
7+
- Concept
8+
- Guide
9+
- Reference
10+
11+
Some developers prefer to read explanatory documentation first and fully before delving into instructive documentation, while other developers start with instructive documentation, and dip into explanatory documentation only as needed. All developers use reference documentation to look up the specifics of APIs as they work with them.
12+
13+
## Concept
14+
15+
Concept documentation helps readers understand a field, concept, or architecture. It is best used for explaining the big picture and design constraints and should be written from the perspective of the developer who is using the system, not from the perspective of the developer who has built it or from the perspective of the system.
16+
17+
In concept documentation, it is often useful to include simple architecture charts and drawings. Additionally, mention and link to the standards and APIs that are being used, so that readers have a point of reference to find additional information. Explain when implementations differ from commonly accepted standards to minimize frustration.
18+
19+
Concept documentation can be read and understood as one document, either in parts or as a whole. Readers may skip a chapter or section, but reading the whole document will help them understand the complete picture.
20+
21+
When describing a feature of the product or technology, try to answer the following questions:
22+
23+
- Who is going to use it?
24+
- What does the feature or technology do?
25+
- When is the feature or technology used?
26+
- Where does it fit into the workflow?
27+
- Why is the feature or technology required/needed/wanted?
28+
- How does the feature or technology work?
29+
30+
Do not include instructions on how to use the feature. Break the usage content into tasks and subtasks and create separate docs for each as appropriate. Provide links to those tasks.
31+
32+
Do not include reference content in a concept doc. Create a separate reference doc and link to it.
33+
34+
Do not explain industry standards that your audience should be familiar with. You might explain how an industry standard ties in with your concept, but you should not explain the basics of that industry standard.
35+
36+
Use simple titles that include the subject only. Avoid words like "Learn about..." and "Introduction to..."
37+
38+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
39+
| --- | --- |
40+
| Custom Database Connections | Custom Database Connections Overview<br>Getting started with custom database connections |
41+
| Hook Extensibility Points | Learning About Extensibility Points When Using Hooks |
42+
| Web Tokens | Why Use JSON Web Tokens (JWTs) vs. Simple Web Tokens (SWTs) |
43+
44+
## Guide
45+
46+
Guides help readers complete a particular task. Developers read instructive documentation with a specific goal in mind, so we should write it to help them get from A to B in the shortest time possible. Instead of in-depth explanations of concepts, guides should explain concepts that are touched in one or two sentences and refer to explanatory documentation for details.
47+
48+
Every instructive documentation should start with a goal: explain what the developer will be able to achieve by following the guide. Make the instructive documentation you write easy to follow by minimizing assumptions and listing all prerequisites. This includes familiarity with programming languages, concepts, installed developer tools, required user accounts, and so on. Each step of the instructions should make clear why it needs to be followed.
49+
50+
Examples are crucial in making instructive documentation easy to follow. Many developers simply copy and paste the examples, so make sure that there is an example for each step along the guide, and that the examples can be copied, pasted and executed. Whenever the developer needs to replace values in the example, highlight these placeholders.
51+
52+
Similar to Concept documentation, guides can be read and understood as one document, either in parts or as a whole. Readers may skip a chapter or section, but reading the whole document will help them understand the complete picture.
53+
54+
When describing a feature of the product or technology, answer the following questions during a task analysis:
55+
56+
- Who typically does the task (audience)?
57+
- What is the goal of the task?
58+
- Why is the task needed (examples)?
59+
- When and where in the workflow should the task take place?
60+
61+
Do not add too much conceptual information in the introduction. Link to the parent concept docs.
62+
63+
Do not add reference sections (tables, lists, best practices, troubleshooting information) that could or may be linked to or used by other guides and concepts. Make them separate docs and link to them.
64+
65+
Use task-oriented titles that describe the performance goals. Avoid functional wording that uses Auth0-specific feature names.
66+
67+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
68+
| --- | --- |
69+
| Use Your Own Database | How to connect a custom database<br>Connecting a custom database |
70+
| Assign and change users | The User Management Tab |
71+
72+
## Reference
73+
74+
Reference documentation is made up of short articles that describe one item in a structured way and are consumed like a dictionary or encyclopedia. You don't read the dictionary—you consult it. This kind of documentation will frequently be looked up and consumed bit by bit.
75+
76+
Like instructive documentation, reference documentation is task-oriented, but the task at hand is a smaller fragment that typically involves refreshing a developer's memory on API usage or configuration parameters.
77+
78+
Some examples that should be reference docs are:
79+
80+
- Logs
81+
- Files
82+
- Restrictions and limitations
83+
- Grant types
84+
- Settings
85+
- Error codes
86+
- Troubleshooting
87+
88+
Write reference documentation so that each item (class, method, API function) can stand on its own. Make references to other items browsable through links. Include examples.
89+
90+
Use simple, straight-forward titles with as few acronyms as possible. Identify what the items or facts relate to and what they are.
91+
92+
| :blue_star: **Preferred** | :blue_star: **Discouraged** |
93+
| --- | --- |
94+
| JSON Web Key Set Property Example | JWKS Demo Tenant Example Properties |
95+
| JSON Web Token Structure | The JWS Structure of a JWT in Auth0 |
96+
| Troubleshoot Custom Domains | Troubleshooting Custom Domains |
97+
| Multi-Tenant Deployment Scenario | How to Setup Multi-Tenant Environments |

0 commit comments

Comments
 (0)