Add Auth0 Docs Style Guide skill for Claude Code

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

@@ -0,0 +1,75 @@
+---
+name: writing-auth0-docs
+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)
+---
+
+# Auth0 Docs Authoring Skill
+
+**Scope:** This skill applies ONLY to the Auth0 docs-v2 repository.
+
+Use this skill when actively authoring new public Auth0 product documentation or fixing style violations in this repository to ensure content aligns with the Auth0 Docs Style Guide.
+
+## When NOT to Use This Skill
+
+**Do NOT load for:**
+- Reading existing docs to understand Auth0 features or APIs
+- Searching docs for information
+- General discussion about documentation content
+- Code implementation (even if docs-related)
+- Navigating or exploring the docs repository
+
+**Only load when actively authoring or correcting documentation style/structure.**
+
+## Quick Reference
+
+| Task | Reference File |
+|------|----------------|
+| Choose doc type (concept/guide/reference) | [documentation-types.md](reference/documentation-types.md), [document-structure.md](reference/document-structure.md) |
+| Voice, tone, user focus | [focus-on-the-user.md](reference/focus-on-the-user.md) |
+| Grammar, tense, pronouns, punctuation | [writing-mechanics.md](reference/writing-mechanics.md) |
+| Tables, notes, callouts, code blocks | [formatting.md](reference/formatting.md) |
+| Terminology, capitalization, UI wording | [word-lists.md](reference/word-lists.md) |
+| Links, images, code, placeholders, UI text | [other-conventions.md](reference/other-conventions.md) |
+| Translation-ready writing | [writing-for-translation.md](reference/writing-for-translation.md) |
+| Deprecations, compliance, Early Access | [operational-policies-and-regulatory-articles.md](reference/operational-policies-and-regulatory-articles.md) |
+| Overview and external resources | [auth0-docs-style-guide.md](reference/auth0-docs-style-guide.md), [references-and-resources.md](reference/references-and-resources.md) |
+
+## Workflow
+
+**Before drafting:**
+- Choose doc type (concept/guide/reference) and title accordingly
+- Plan headings for scannability, focus on one primary topic
+- Note required terminology and compliance constraints
+
+**While writing:**
+- Voice/tone: Clear, approachable, user-focused
+- Grammar: Present tense, active voice, imperative mood for instructions
+- Headings: Sentence case (not title case)
+- Language: Inclusive, accessible, avoid idioms/jargon
+- Terminology: Use Word Lists for Auth0 features, capitalization
+- Formatting: Follow rules for links, images, alt text, code blocks
+
+**For translation readiness:**
+- Short, unambiguous sentences
+- Avoid and/or, (s) plurals, idiomatic phrasal verbs
+- Define abbreviations on first use
+- Reuse existing phrasing for translation memory
+
+**For compliance/regulatory:**
+- Legal/Security/Compliance teams are source of truth
+- Follow structure for Early Access, Beta, deprecation notices
+- Include required dates, replacement features, migration links
+
+**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.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Title case for headings | Use sentence case (only first word capitalized) |
+| Warning for Enterprise plan restrictions | Use Callout with `icon="file-lines" color="#0EA5E9"` |
+| Placeholder format `{{VAR}}` | Use `YOUR_SOMETHING` or `<something-id>` conventions |
+| Passive voice in instructions | Use active voice and imperative mood |
+| Using and/or or (s) for plurals | Write out both options or rephrase for clarity |
+| Generic "click here" links | Use descriptive link text |
+| Missing alt text for images | Provide specific, descriptive alt text |

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

@@ -0,0 +1,19 @@
+# Auth0 Docs Style Guide
+
+### Overview
+
+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.
+
+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.
+
+Some of these guidelines are adapted and remixed from Google's Developer Documentation Style Guide and Microsoft Writing Style Guide, per Creative Commons License.
+
+## Style standards
+
+In general, we use American English according to the standards described in the Associated Press's (AP) Stylebook. For general software-industry styles and terminology, refer to the Microsoft Writing Style Guide.
+
+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.
+
+## Accessibility and inclusivity
+
+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. 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

@@ -0,0 +1,119 @@
+# Document Structure
+
+Document structure describes the organization of a document into graphical elements, such as sections, paragraphs, and sentences.
+
+### Headings
+
+Use short headings to group related paragraphs and clearly describe the sections. Good headings provide an outline of the content.
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| Use clear section headings to organize content logically | Avoid walls of text without clear heading structure |
+
+### Verb forms
+
+In headings with verbs, avoid the infinitive and gerund form and use the simple tense.
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| Connect a custom database | How to connect a custom database<br>Connecting a custom database |
+| Assign and change users | Assigning and changing users |
+
+### Ambiguity
+
+Include all words that you need to clarify what is in the section.
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| IP routing protocols | Routing protocols |
+| Use scripts to monitor user activity | Monitoring scripts |
+| Suggestions for setting up user metadata | Things to consider |
+| Reverse proxy server requirements | Requirements |
+
+### Capitalization
+
+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).
+
+Use sentence case for headings. Capitalize only the first word of each heading (unless it is case-sensitive) and all proper nouns.
+
+### Singular vs. plural forms
+
+Use the plural form of nouns in headings unless the singular form is obviously required.
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| Restore backup files | Restoring a backup file |
+| Create Delegated Admin Applications | Create a Delegated Admin Application |
+| Install the Delegated Admin Extension | Installing the Delegated Admin Extension |
+
+## Content
+
+### Introductory text
+
+In the first few sentences, try to describe who, what, and when. Include an example if possible.
+
+Avoid using phrases like:
+- This guide will show...
+- This tutorial shows you...
+- This article describes...
+- This document...
+- Auth0 offers...
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| 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. |
+| 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. |
+
+### Body text
+
+In general, keep paragraphs short for internet reading.
+
+Also, consider the following:
+- Subheadings are not independent statements. Repeat the information from the subheading in the paragraph.
+- When mentioning several elements, use lists.
+- Avoid abbreviations. Use “for example” instead of “e.g.” Do not use “etc”.
+- Refer to the developer's customer as the "user".
+- If you need to use the name of a fictional company, use "ExampleCo".
+- Don't pre-announce anything. Avoid “currently” or “available in an upcoming release”.
+- Avoid overusing adjectives or adverbs. Never use more than two in a sentence.
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| 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. |
+| 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. |
+
+### Steps
+
+Use the imperative form for steps.
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| Save authentication data. | Authentication data should be saved. |
+| Set user email preferences. | Email preferences can be set. |
+
+If an action is required, use "must".
+
+If an action is available, use "can".
+
+If an action is optional, use "may".
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| To limit access to your resources, you must use scopes. | To limit access to your resources, you should use scopes. |
+| To limit access to your resources, use scopes. | You might want to use scopes to limit access to your resources. |
+| You may want to create more access roles. | Creating more access roles is possible. |
+
+Use "select" when referring to text links in a webpage or UI components. Remember that the UI may be rendered differently on different devices
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| Select **Save**. | Click **Save**. |
+| Select **Go to Settings** to access the settings section. | Click **Go to Settings** to access the settings section. |
+
+Depending on the situation, the reader can "gain access", "grant access", or "allow access".
+
+## Nesting
+
+Avoid deep nesting of document structure. Three levels of headings are usually enough.
+
+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

@@ -0,0 +1,93 @@
+# Documentation Types
+
+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.
+
+In support of this, there are three documentation types:
+- Concept
+- Guide
+- Reference
+
+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.
+
+## Concept
+
+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.
+
+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.
+
+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.
+
+When describing a feature of the product or technology, try to answer the following questions:
+- Who is going to use it?
+- What does the feature or technology do?
+- When is the feature or technology used?
+- Where does it fit into the workflow?
+- Why is the feature or technology required/needed/wanted?
+- How does the feature or technology work?
+
+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.
+
+Do not include reference content in a concept doc. Create a separate reference doc and link to it.
+
+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.
+
+Use simple titles that include the subject only. Avoid words like "Learn about..." and "Introduction to..."
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| Custom Database Connections | Custom Database Connections Overview<br>Getting started with custom database connections |
+| Hook Extensibility Points | Learning About Extensibility Points When Using Hooks |
+| Web Tokens | Why Use JSON Web Tokens (JWTs) vs. Simple Web Tokens (SWTs) |
+
+## Guide
+
+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.
+
+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.
+
+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.
+
+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.
+
+When describing a feature of the product or technology, answer the following questions during a task analysis:
+- Who typically does the task (audience)?
+- What is the goal of the task?
+- Why is the task needed (examples)?
+- When and where in the workflow should the task take place?
+
+Do not add too much conceptual information in the introduction. Link to the parent concept docs.
+
+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.
+
+Use task-oriented titles that describe the performance goals. Avoid functional wording that uses Auth0-specific feature names.
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| Use Your Own Database | How to connect a custom database<br>Connecting a custom database |
+| Assign and change users | The User Management Tab |
+
+## Reference
+
+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.
+
+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.
+
+Some examples that should be reference docs are:
+- Logs
+- Files
+- Restrictions and limitations
+- Grant types
+- Settings
+- Error codes
+- Troubleshooting
+
+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.
+
+Use simple, straight-forward titles with as few acronyms as possible. Identify what the items or facts relate to and what they are.
+
+| ✅ **Preferred** | ❌ **Discouraged** |
+| --- | --- |
+| JSON Web Key Set Property Example | JWKS Demo Tenant Example Properties |
+| JSON Web Token Structure | The JWS Structure of a JWT in Auth0 |
+| Troubleshoot Custom Domains | Troubleshooting Custom Domains |
+| Multi-Tenant Deployment Scenario | How to Setup Multi-Tenant Environments |

.claude/skills/writing-auth0-docs/reference/focus-on-the-user.md

@@ -0,0 +1,25 @@
+# Focus on the User
+
+We take a user-centered approach to creating content, which focuses on the impact we want to have on our audience's behavior.
+
+### Voice and tone
+
+We prefer a voice and tone that is natural, approachable, and respectful without being overly informal or whimsical. Avoid writing exactly the way you speak—you probably speak less concisely and more colloquially than you should write—but aim for a conversational, human tone.
+
+Remember that many readers are not native English speakers, that they come from many different cultures, and that your document may be translated into other languages. Use clear, precise language, short sentences, and brief three-to-five sentence paragraphs. When discussing complex or formal concepts, follow them with an explanation.
+
+In general, remember to put the user first; what matters most is what readers can do with our technology for their users.
+
+## Scannability
+
+To make your documentation easy to read:
+- Keep your documents short: five minutes reading time per page (about 6,000 words) is ideal. Documents should be no longer than 10 minutes reading time (about 12,000 words).
+- Introduce links between documents, for instance a "Getting Started Guide" and a "Production Readiness Guide" or "Core Concepts" and "Deep Dives".
+
+## Findability
+
+Your documentation is not useful if it cannot be found and if it will not be read. To make your documentation easy to find:
+- Use page titles and URLs that include keywords a developer would search for.
+- Include the programming languages and APIs that are being used and explained in the page title and include the action that will be performed.
+- Many search engines cut titles off after 60 characters, so keep titles shorter by leaving off "how to".
+- Restrict your documentation to one topic per page. As developers are searching for specific topics, search engines will rank pages higher that are all about that one topic, not multiple things at once.