Docs Writer

# Style Guide: Quota vs. Limit

This guide defines the usage of "quota," "limit," and related terms in
user-facing interfaces.

## TL;DR

- **`quota`**: The administrative "bucket." Use for settings, billing, and
  requesting increases. (e.g., "Adjust your storage **quota**.")
- **`limit`**: The real-time numerical "ceiling." Use for error messages when a
  user is blocked. (e.g., "You've reached your request **limit**.")
- **When blocked, combine them:** Explain the **limit** that was hit and the
  **quota** that is the remedy. (e.g., "You've reached the request **limit** for
  your developer **quota**.")
- **Related terms:** Use `usage` for consumption tracking, `restriction` for
  fixed rules, and `reset` for when a limit refreshes.

---

## Detailed Guidelines

### Definitions

- **Quota is the "what":** It identifies the category of resource being managed
  (e.g., storage quota, GPU quota, request/prompt quota).
- **Limit is the "how much":** It defines the numerical boundary.

Use **quota** when referring to the administrative concept or the request for
more. Use **limit** when discussing the specific point of exhaustion.

### When to use "quota"

Use this term for **account management, billing, and settings.** It describes
the entitlement the user has purchased or been assigned.

**Examples:**

- **Navigation label:** Quota and usage
- **Contextual help:** Your **usage quota** is managed by your organization. To
  request an increase, contact your administrator.

### When to use "limit"

Use this term for **real-time feedback, notifications, and error messages.** It
identifies the specific wall the user just hit.

**Examples:**

- **Error message:** You’ve reached the 50-request-per-minute **limit**.
- **Inline warning:** Input exceeds the 32k token **limit**.

### How to use both together

When a user is blocked, combine both terms to explain the **event** (limit) and
the **remedy** (quota).

**Example:**

- **Heading:** Daily usage limit reached
- **Body:** You've reached the maximum daily capacity for your developer quota.
  To continue working today, upgrade your quota.


# Procedural Guide: Auditing the Docset

This guide outlines the process for auditing the Gemini CLI documentation for
correctness and adherence to style guidelines. This process involves both an
"Editor" and "Technical Writer" phase.

## Objective

To ensure all public-facing documentation is accurate, up-to-date, adheres to
the Gemini CLI documentation style guide, and reflects the current state of the
codebase.

## Phase 1: Editor Audit

**Role:** The editor is responsible for identifying potential issues based on
style guide violations and technical inaccuracies.

### Steps

1.  **Identify Documentation Scope:**
    - Read `docs/sidebar.json` to get a list of all viewable documentation
      pages.
    - For each entry with a `slug`, convert it into a file path (e.g., `docs` ->
      `docs/index.md`, `docs/get-started` -> `docs/get-started.md`). Ignore
      entries with `link` properties.

2.  **Prepare Audit Results File:**
    - Create a new Markdown file named `audit-results-[YYYY-MM-DD].md` (e.g.,
      `audit-results-2026-03-13.md`). This file will contain all identified
      violations and recommendations.

3.  **Retrieve Style Guidelines:**
    - Familiarize yourself with the `docs-writer` skill instructions and the
      included style guidelines.

4.  **Audit Each Document:**
    - For each documentation file identified in Step 1, read its content.
    - **Review against Style Guide:**
      - **Voice and Tone Violations:**
        - **Unprofessional Tone:** Identify phrasing that is overly casual,
          defensive, or lacks a professional and friendly demeanor.
        - **Indirectness or Vagueness:** Identify sentences that are
          unnecessarily wordy or fail to be concise and direct.
        - **Incorrect Pronoun:** Identify any use of third-person pronouns
          (e.g., "we," "they," "the user") when referring to the