Writing for AI
This page demonstrates how I write documentation that AI systems can retrieve, process, and reason about accurately.
This exhibit covers the full NimbusWiz documentation corpus and shows the chunking strategy, metadata schema, restructuring patterns applied across the corpus. I've also attempted an evaluation dataset for testing retrieval accuracy.
Why docs written for humans could fail in RAG systems
Documentation for humans is optimised for narrative flow, progressive disclosure, and contextual understanding. A human reader arrives with prior context; they know the product, they are reading sequentially, and they can resolve ambiguity from surrounding paragraphs.
A RAG system has none of that context. It chunks documents into segments, embeds each chunk as a vector, and retrieves the most semantically similar chunks for a given query. Three specific failure patterns affect the NimbusWiz corpus as originally written:
-
Pronoun dependency: Phrases like "it runs automatically" or "this feature" rely on the preceding paragraph for referent resolution. In an extracted chunk, the referent is lost.
-
Contextual headings: A heading like "First-time setup" is meaningful on a page titled "Getting started." Extracted as a chunk, it has no product anchor. A model cannot determine what product or workflow "first-time" refers to.
-
Distributed definitions: NimbusWiz terms defined in one section and used without definition elsewhere, such as Quirk Intelligence, Flight Profile, and Simulation Mode, produce partial, inconsistent answers when retrieved from different chunks.
The chunk metadata schema
Before restructuring any content, I defined a metadata schema that applies consistently across all content pages. This is the IA work that makes AI-optimised documentation maintainable rather than ad hoc.
# Standard frontmatter (already present on all pages)
title: string
description: string # Expanded to include product context
content_type: guide | reference | concept | overview | exhibit
audience: all | devops-engineer | system-admin | technical-manager
# AI-specific additions
keywords: [list] # Explicit retrieval signals
chunk_strategy: sequential | parallel | standalone
# sequential: chunks depend on pipeline order
# parallel: chunks are independent topics
# standalone: single-chunk page
related_pages: [list] # Cross-page retrieval links
Each page also uses inline chunk markers:
[CHUNK: chunk-id ]
**Context:** [One sentence establishing product and feature context]
[Content]
**Standalone summary:** [One to two sentences summarising this chunk
for broad retrieval queries]
[END CHUNK: chunk-id ]
The **Context:** sentence at the start of every chunk is the most
important structural change. It makes each chunk self-contained; a model receiving only that chunk knows the product, the feature,
and the user's context without needing adjacent chunks.
Restructuring examples (one per doc suite)
Click for more.
User guide: Getting started
Original (human-optimised):
When you open NimbusWiz, a Getting Started banner appears at the top
of the Dashboard. The banner has four steps:
1. Connect a System.
2. Run Fleet Scan.
3. View Recommendations.
4. Apply or Preview.
The banner tracks your progress as you complete each step.
To close it, select Dismiss in the banner.
Restructured (AI-optimised):
[CHUNK: getting-started-banner ]
**Context:** NimbusWiz is an enterprise SaaS platform for modernizing
legacy Nimbus2000-class systems. The Getting Started banner appears at
the top of the Dashboard when you first open NimbusWiz.
When you open NimbusWiz, a **Getting Started** banner appears at the
top of the Dashboard. The banner has four orientation steps:
1. **Connect a System**: Register your first Nimbus system so NimbusWiz
has something to analyze.
2. **Run Fleet Scan**: Analyze system health and dependencies.
3. **View Recommendations**: See intelligent upgrade suggestions.
4. **Apply or Preview**: Deploy a safe profile, or run a simulation to
preview the outcome before committing.
The banner tracks your progress as you complete each step. To close it,
select **Dismiss** in the banner. The banner reappears each session
until you dismiss it.
**Standalone summary:** The NimbusWiz Getting Started banner is a
four-step orientation guide that appears at the top of the Dashboard.
Steps: Connect a System, Run Fleet Scan, View Recommendations, Apply or
Preview. Select Dismiss to close the banner; it reappears each session
until dismissed.
[END CHUNK: getting-started-banner ]
Changes: Product context sentence added, UI labels bolded throughout, step descriptions expanded to be self-contained, standalone summary added for broad queries, pronoun "it" replaced with "The NimbusWiz Getting Started banner."
Admin guide: Role-based access control
Original (human-optimised):
NimbusWiz has three roles. Every user is assigned exactly one role.
| Role | Capabilities |
|------|-------------|
| Viewer | Read-only access to all screens. |
| Operator | All Viewer capabilities plus: run scans, apply upgrades... |
| Admin | All Operator capabilities plus: manage users, rotate API keys... |
Restructured (AI-optimised):
[CHUNK: rbac-roles ]
**Context:** NimbusWiz uses role-based access control (RBAC) to govern
what each user can do. Every NimbusWiz user has exactly one role, set
at invitation and changeable only by an Admin.
NimbusWiz has three roles:
| Role | Access level | Key capabilities |
|------|-------------|-----------------|
| **Viewer** | Read-only | View all screens and data. Cannot run scans, apply upgrades, trigger deployments, or change settings. |
| **Operator** | Task execution | All Viewer access plus: run scans, apply upgrade profiles, manage deployments, create automation pipelines, use the Developer Hub. |
| **Admin** | Full platform | All Operator access plus: manage users and roles, generate and revoke API keys, configure integrations and webhooks, access Audit Logs, change organization settings. |
A user's current role is shown in the **Current Role** badge at the
bottom of the NimbusWiz sidebar.
**Standalone summary:** NimbusWiz has three user roles: Viewer
(read-only), Operator (task execution), and Admin (full platform access
including user management and governance). Every user has exactly one
role, visible in the sidebar Role badge.
[END CHUNK: rbac-roles ]
Changes: RBAC acronym expanded on first use, table enhanced with "Access level" column for clearer retrieval, current role location added, standalone summary covers the three roles for broad "what are the roles" queries.
Knowledge base: Modernization Advisor confidence score
Original (human-optimised):
### What does the confidence score mean?
The confidence score (0–100%) reflects how much data the Modernization Advisor has
to work with. A higher score means the recommendation is based on more
complete information.
Restructured (AI-optimised):
[CHUNK: advisor-confidence-score ]
**Context:** The NimbusWiz Modernization Advisor generates upgrade
recommendations with a confidence score. The score reflects data
completeness, not prediction accuracy.
**What does the Modernization Advisor confidence score mean?**
The confidence score (0–100%) reflects how much data the Modernization Advisor has
to work with: specifically, the completeness of the system's scan
results, Quirk Profile, and Flight Profile.
| Score range | Meaning | Recommended action |
|-------------|---------|-------------------|
| 80–100% | High confidence | Act on the recommendation |
| 60–79% | Moderate confidence | Consider running another scan first |
| Below 60% | Low confidence | Run additional scans, set a Flight Profile, or allow more monitoring time |
A high confidence score does not guarantee the recommended upgrade will
succeed. It means the Modernization Advisor has sufficient data to make a reliable
recommendation. A low confidence score means the Modernization Advisor needs more
information, not that the recommendation is wrong.
**Standalone summary:** The NimbusWiz Modernization Advisor confidence
score (0–100%) measures data completeness, not prediction accuracy.
Below 60% means the Modernization Advisor needs more scans or a Flight Profile set.
Above 80% means sufficient data exists to act on the recommendation.
[END CHUNK: advisor-confidence-score ]
Changes: Distinction between data completeness and prediction accuracy made explicit (a common misconception), three-tier table added for structured retrieval, standalone summary covers both the definition and the action thresholds.
API reference: Authentication
Original (human-optimised):
## Bearer token
Include your API key in the `Authorization` header of every request:
Authorization: Bearer YOUR_API_KEY
Requests without a valid `Authorization` header return `401 Unauthorized`.
Restructured (AI-optimised):
[CHUNK: api-authentication ]
**Context:** All NimbusWiz API requests to `https://api.nimbuswiz.io/v1`
require authentication using a Bearer token. NimbusWiz uses API keys,
not OAuth or session cookies.
**How to authenticate NimbusWiz API requests:**
Include your NimbusWiz API key in the `Authorization` header of every
request:
Authorization: Bearer YOUR_API_KEY
| Response | Cause |
|----------|-------|
| `401 Unauthorized` | Missing `Authorization` header, invalid key, or revoked key |
| `403 Forbidden` | Valid key but insufficient scope for the requested endpoint |
API keys are generated in **Developer Hub → API Keys** inside NimbusWiz.
Keys have scoped permissions. A key with `fleet:read` scope cannot
access deployment endpoints.
**Standalone summary:** NimbusWiz API authentication uses Bearer tokens
in the `Authorization` header. Missing or invalid keys return 401.
Insufficient scope returns 403. Keys are generated in Developer Hub
and have scoped permissions (fleet:read, fleet:write, deploy:read,
deploy:write).
[END CHUNK: api-authentication ]
Changes: Base URL added to context sentence, authentication method named explicitly (Bearer token, not OAuth), 401 vs 403 distinction made into a table for clean retrieval, scope system introduced in context so auth and scope questions can be answered from a single chunk.
Evaluation dataset: full corpus
52 Q&A pairs grounded in the actual content of each page - headings, procedures, and definitions as they currently exist. Designed to test retrieval accuracy, answer completeness, and cross-chunk reasoning.
Click for more.
User guide (16 questions)
| ID | Question | Expected answer summary | Source chunk |
|---|---|---|---|
| UG01 | What is NimbusWiz? | Enterprise SaaS platform for modernizing legacy Nimbus2000-class systems. Decision platform, not just an upgrade tool. | index |
| UG02 | What is the Getting Started banner and what are its steps? | A four-step orientation banner that appears at the top of the Dashboard when you first open NimbusWiz. Steps: Connect a System, Run Fleet Scan, View Recommendations, Apply or Preview. Select Dismiss to close it; the banner reappears each session until dismissed. | getting-started-banner |
| UG03 | What is Demo Mode and how is it different from real data? | Demo Mode toggles the app to pre-filled data. Real systems are never affected. Toggle is in the sidebar. | getting-started-demo-mode |
| UG04 | What are the three NimbusWiz user roles? | Viewer (read-only), Operator (task execution), Admin (full platform access). Every user has exactly one role. | getting-started-roles |
| UG05 | What format must a NimbusWiz System ID follow? | nimbus-[name]-[number], for example nimbus-alpha-001. Unique, immutable after registration. | register-system-id |
| UG06 | What is a Flight Profile and where is it set? | Per-system operational priority: Performance-focused, Stability-focused, or Efficiency-focused. Set on the System Detail page. Influences Modernization Advisor recommendations. | register-flight-profile |
| UG07 | What does the assessment gate determine? | Pass: Proceed to Modernization Advisor button activates. Fail: routed to Troubleshooting. Determined by whether High-risk components remain unresolved. | assess-gate |
| UG08 | What does the Modernization Advisor Insight summary show? | A plain-language summary of the scan result: risk level, key findings, and the recommended next action. Appears at the top of the assessment results. | assess-advisor-insight |
| UG09 | What does the Modernization Advisor confidence score mean? | 0–100% measure of data completeness, not prediction accuracy. Below 60% means more scans or a Flight Profile needed. Above 80% means sufficient data to act. | recommendation-confidence-score |
| UG10 | What are the three upgrade profiles in NimbusWiz? | Stable (conservative), Performance (balanced speed and reliability), Extended Operation (preserves legacy behaviours). Selected on the Modernize page. | modernize-upgrade-profile |
| UG11 | What must happen before the Deploy button activates? | The pre-upgrade simulation must pass. The Deploy button remains inactive until a passing simulation is recorded. | modernize-simulation-gate |
| UG12 | What are the deployment status stages? | Preparing, Executing, Monitoring, Completed. Also: Failed, Rolling back, Rolled back. | deploy-status |
| UG13 | How do I roll back a deployment in NimbusWiz? | Select Rollback on the Deployment page and confirm. Available during Preparing, Executing, and Monitoring stages. Not available once Completed. | deploy-rollback |
| UG14 | What are the three core monitoring metrics? | Stability Index (reliability and uptime, 0–100), Responsiveness Score (response time consistency, 0–100), Network Interaction (network quality, 0–100). | monitor-metrics |
| UG15 | What does System Modernized status mean? | Badge applied when a system completes the full pipeline and monitoring metrics are consistently healthy. Not permanent; resets if metrics fall below thresholds. | monitor-modernized |
| UG16 | What are the available event hooks in NimbusWiz? | System Health Critical, Deployment Completed, New Security Patch Available, Stability Below Threshold. Event hooks run inside NimbusWiz and trigger an action when the named event occurs. | automation-events |
Admin guide (12 questions)
| ID | Question | Expected answer summary | Source chunk |
|---|---|---|---|
| AG01 | What additional capabilities does the Admin role have over Operator? | Manage users and roles, generate and revoke API keys, configure integrations and webhooks, access Audit Logs, change organization settings. | initial-setup-roles |
| AG02 | What happens to a user's pipelines when they are removed from NimbusWiz? | Pipelines are orphaned and they stop running. An Admin must reassign them. Covered under automation-admin: reassigning pipelines after user removal. | user-management-remove |
| AG03 | What are the four NimbusWiz API key scopes? | fleet:read, fleet:write, deploy:read, deploy:write. Scopes are set at creation and cannot be changed afterwards. | api-key-scopes |
| AG04 | How do I rotate a NimbusWiz API key with zero downtime? | Generate new key, update all integrations using the old key, verify the new key works, then revoke the old key. This order matters; revoke last. | api-key-rotation |
| AG05 | What is the difference between a webhook and an integration in NimbusWiz? | Integrations connect NimbusWiz to external platforms (GitHub Actions, Datadog, Slack) via OAuth or API. Webhooks send HTTP POST payloads to a URL you control on specific events. | webhooks-vs-integrations |
| AG06 | How does NimbusWiz handle failed webhook deliveries? | Retries three times: after 30 seconds, 5 minutes, and 30 minutes. After three failures, delivery is marked failed. Check Delivery Log in Developer Hub. | webhooks-retry |
| AG07 | What event categories are recorded in NimbusWiz Audit Logs? | Authentication, Users, Systems, Scans, Deployments, API keys, Integrations, Automation, Settings. | audit-logs-categories |
| AG08 | What are the three compliance workflow use cases for Audit Logs? | Change management audit, access review, incident investigation. A fourth (API key audit) is also documented. | audit-logs-compliance |
| AG09 | How long are NimbusWiz audit log entries retained? | Audit log retention is not implemented in the NimbusWiz prototype. In a production deployment, this section would document the retention period, archiving behavior, and export options available before entries expire. | audit-logs-retention |
| AG10 | What are the weekly proactive maintenance habits recommended in NimbusWiz? | Review the Systems at Risk widget on the Dashboard, check the Predictive Insights panel in Monitoring for systems showing declining trends, and review the Scheduled Jobs list to confirm every job ran successfully. | maintenance-proactive |
| AG11 | How can an Admin restrict Demo Mode access in NimbusWiz? | In the sidebar, select Settings, then select the Organization tab, toggle Demo Mode access to Admin only, and select Save settings. When restricted, the Demo Mode button is hidden for Operator and Viewer accounts. | maintenance-demo-mode |
| AG12 | What Dashboard widgets does NimbusWiz provide for fleet health oversight? | Systems at Risk (lists systems with Stability Index below 50 or active Critical or Warning alerts) and Recommended Actions (surfaces organization-level Modernization Advisor recommendations). Used as the starting point for daily fleet health review. | maintenance-fleet-health |
Knowledge base (12 questions)
| ID | Question | Expected answer summary | Source chunk |
|---|---|---|---|
| KB01 | What does the NimbusWiz Stability Score mean? | 0–100 measure of system reliability and uptime consistency. Below 50: high risk. 50–74: moderate. 75–100: healthy. | systems-stability-score |
| KB02 | What are the five tabs on the System Detail page? | Overview, Assessment, Modernization, Deployment, Quirk Profile. (Exact tab names should be verified against the current UI.) | systems-detail-tabs |
| KB03 | How long does a NimbusWiz scan take? | Two to five minutes typically. The scan continues in the background if you navigate away, but the progress indicator may reset. | assessment-scan-duration |
| KB04 | What does the risk heatmap table show? | Components ranked by risk level (High, Medium, Low) with recommended actions for each. Used to identify blockers before the assessment gate. | assessment-risk-heatmap |
| KB05 | How do I improve a low Modernization Advisor confidence score? | Run additional scans, set or update the Flight Profile, or allow more monitoring time to accumulate behavioral data. | advisor-improve-confidence |
| KB06 | Do I have to run a simulation before deploying? | Yes. The simulation is a required gate. The Deploy button does not activate until the simulation passes. Cannot be bypassed from the UI. | simulation-required |
| KB07 | What does a staged rollout mean in NimbusWiz? | The upgrade is applied in phases. If an early phase fails, deployment stops automatically and rollback is triggered, limiting blast radius. | deployment-staged-rollout |
| KB08 | What are the three alert severity levels? | Critical (immediate attention, system degrading or failed), Warning (approaching threshold, act soon), Info (notable event, no immediate action required). | monitoring-alert-severity |
| KB09 | What are predictive insights in NimbusWiz? | AI-generated signals that identify metrics trending toward risk thresholds before an alert fires. Shown on the Monitoring page. | monitoring-predictive-insights |
| KB10 | What is the NimbusWiz API rate limit? | 1,000 requests per minute per API key. Exceeded limit returns 429 Too Many Requests with a Retry-After header. | developer-hub-rate-limit |
| KB11 | I forgot to copy my API key. What do I do? | The key cannot be retrieved after generation. Revoke the key and generate a new one. Update integrations before revoking to avoid downtime. | troubleshooting-lost-key |
| KB12 | The Deploy button is greyed out after the simulation. Why? | The simulation did not pass, or no simulation has been run. The Deploy button only activates after a passing simulation. Re-run the simulation and check warning indicators. | troubleshooting-deploy-greyed |
API reference (12 questions)
| ID | Question | Expected answer summary | Source chunk |
|---|---|---|---|
| AP01 | What is the NimbusWiz API base URL? | https://api.nimbuswiz.io/v1 | api-index |
| AP02 | How do I authenticate NimbusWiz API requests? | Include the API key as a Bearer token in the Authorization header. Missing or invalid key returns 401. Insufficient scope returns 403. | api-authentication |
| AP03 | What are the three rate limit response headers? | X-RateLimit-Limit (max requests per minute), X-RateLimit-Remaining (remaining in current window), X-RateLimit-Reset (Unix timestamp of window reset). | rate-limits-headers |
| AP04 | What does the fleet:write scope allow? | POST /v1/fleet (register a system) and PATCH /v1/fleet/{system_id} (update system metadata). | api-scopes |
| AP05 | What does POST /v1/fleet/{system_id}/scan return? | A scan job object with job_id and status: queued. This is an async endpoint. The results are retrieved separately via GET /v1/scans/{job_id}. | scan-initiate |
| AP06 | How often should I poll for NimbusWiz scan results? | No more frequently than once every 10 seconds. Most scans complete within two to five minutes. | scan-polling |
| AP07 | What does setting simulation_required to false do? | Bypasses the dry-run gate. The deployment proceeds without a passing simulation. Not recommended for production systems. | deployment-simulation-required |
| AP08 | When is rollback available via the API? | When deployment status is preparing, executing, or monitoring. Returns 409 Conflict if status is completed, failed, or already rolled_back. | deployment-rollback-availability |
| AP09 | What HTTP code does the NimbusWiz API return for an active deployment conflict? | 409 Conflict, with error code deployment_in_progress and the active deployment_id in the detail object. | error-codes-conflict |
| AP10 | What does the 422 simulation_required error mean? | A deployment was attempted without a passing simulation when simulation_required is true. Run a simulation first or set simulation_required to false. | error-codes-422 |
| AP11 | How does NimbusWiz signal a deprecated API endpoint? | Via the Deprecation: true response header plus a Sunset header with the removal date. NimbusWiz gives 6 months notice before removing any endpoint. | changelog-deprecation |
| AP12 | How do I verify a NimbusWiz webhook payload? | Compute HMAC-SHA256 of the raw request body using the webhook secret. Compare to the X-NimbusWiz-Signature header using constant-time comparison. Examples provided in Node.js and Python. | webhooks-verification |
Cross-chunk questions
Six questions requiring information from two or more chunks. Tests whether the retrieval system returns complete context, not just the nearest match.
| ID | Question | Required chunks |
|---|---|---|
| XC01 | How does the Flight Profile affect the Modernization Advisor recommendation? | register-flight-profile + recommendation-confidence-score |
| XC02 | What should I do if the simulation fails and I want to proceed anyway? | modernize-simulation-gate + deployment-simulation-required |
| XC03 | If I remove a user, what happens to their API keys and their pipelines? | user-management-remove + api-key-rotation + automation-admin-reassign |
| XC04 | What is the difference between a 401 and a 403 API error, and what causes each? | api-authentication + error-codes-table |
| XC05 | How do predictive insights differ from alerts, and which should I act on first? | monitoring-predictive-insights + monitoring-alert-severity |
| XC06 | How do I set up a webhook and verify its signature in my application? | webhooks-admin-configure + webhooks-verification |
Coverage summary
| Suite | Pages | Chunks | Eval questions |
|---|---|---|---|
| User guide | 12 | 38 | 16 |
| Admin guide | 9 | 27 | 12 |
| Knowledge base | 10 | 30 | 12 |
| API reference | 10 | 32 | 12 |
| Cross-chunk | — | — | 6 |
| Total | 41 | 127 | 52 |
The broader principle
Writing for AI consumption does not require a separate document. It requires a documentation practice applied consistently across the corpus.
Three rules that produced the most improvement across the NimbusWiz corpus:
Every chunk must answer one question completely: The chunk boundary is not a page break or a heading; it is the boundary of a complete answer. If a user could ask a question and the answer spans two chunks, either merge them or add a standalone summary to each.
Every chunk must name the product and feature in its first sentence: Not "The banner tracks your progress." It needs to read "The NimbusWiz Getting Started banner tracks your progress." This single change eliminates the largest category of retrieval failures across the corpus: pronoun dependency on adjacent context.
The description frontmatter field is a retrieval asset, not a meta tag: Every NimbusWiz page description was rewritten to include: the product name, the feature or topic, and the user's job-to-be-done. This makes the description function as a high-quality retrieval target for broad queries that do not match any specific chunk.
These changes make the documentation better for human readers too. Concise, self-contained sections with explicit context are easier to scan, easier to search, and easier to translate. The investment in AI-optimised structure pays compound returns across every downstream use of the content.