Skip to content
SmartSite Assistant SmartSite Assistant

Update and Validate Documentation

Implementation changes must be traced end-to-end before documentation text, screenshots, matrix rows, or version claims are changed.

Documentation maintenance repeats the original evidence process at a smaller scope. A changed control is traced from view label through JavaScript, handler, sanitation, saved option, runtime use, errors, privacy, and frontend effect. The guide, control reference, feature matrix, maintainer report, screenshot brief, and validators then change together.

A reliable setup moves from confirm the plugin bootstrap version and compare readme only as a secondary source to the point where you deploy the docs container without changing plugin or other services. The controls below explain the decisions along that path, including settings that support the conversation without changing the model’s answer directly.

What this feature does and when to use it

Section titled “What this feature does and when to use it”

Use this workflow for every plugin release or material admin/frontend change.

Use this feature in the following situations:

  • A plugin release changes visible behavior, defaults, limits, permissions, storage, or dependencies.
  • A discrepancy is reported between the documentation and a deployed screen.
  • You are adding a new sidebar page or screenshot and need all generated artifacts reconciled.

Where to find it

Section titled “Where to find it”
WordPress locationDocumentation project → audit + src/data + src/content/docs

Before you begin

Section titled “Before you begin”
  • A clean/read-only copy of the new first-party plugin source.
  • Ability to run repository search, PHP/JavaScript inspection, and the documentation validation suite.
  • Owner access for uncertain UI/runtime behavior that cannot be proven safely.

Set it up step by step

Section titled “Set it up step by step”
  1. Confirm the plugin bootstrap version and compare README only as a secondary source.
  2. Inventory first-party file changes; exclude vendor internals.
  3. Trace each affected UI control through JavaScript/PHP handler, saved state, runtime, errors, and security.
  4. Update audit/feature-coverage.md and audit/maintainer-report.md.
  5. Update catalog guide content and generated MDX pages.
  6. Update screenshot capture instructions/inventory and replace images when available.
  7. Run the complete validation suite and inspect the production preview.
  8. Deploy the docs container without changing plugin or other services.

Fields, controls, and important values

Section titled “Fields, controls, and important values”

The artifacts below keep a documentation change tied to implementation evidence and to every page that depends on it. They do not affect AI responses directly, but inaccurate guidance can lead an administrator to choose the wrong model, omit useful metadata, expose a tool, or misread a security state. Validation makes those documentation failures visible before publishing.

Fields, controls, and important values
Field, control, or statusWhat SmartSite Assistant does with itHow to use it and why it matters
Feature coverage matrix Maps feature, user, admin location, proof, prerequisites/defaults/workflow/result/limits/privacy/failures/page/screenshots. The choice in “Feature coverage matrix” decides where this feature is available. It may affect who can ask the AI or which profile sees a tool, but it does not make the resulting answer safer unless the underlying operation also checks access.
Maintainer report Records version, sources, features, pages, discrepancies, assumptions, uncertainty, and outstanding captures. Record the inspected release, important evidence, discrepancies, assumptions, uncertainties, validation result, and outstanding captures in one handoff. This gives future authors the context needed to distinguish a documentation gap from an unresolved plugin behavior.
Catalog Central structured content rendered by each Starlight MDX page. The structured catalog is the editable source for workflows, controls, troubleshooting, links, and screenshot contracts. Generated MDX should remain disposable; changing it directly creates improvements that vanish the next time pages are regenerated.
Validation script Reconciles catalog, generated pages, sidebar, links, screenshots, assets, placeholder fields, forbidden demo text, and likely secrets. The custom checks reconcile catalog entries with routes, navigation, required explanations, screenshots, assets, links, secrets, tables, and built output. Extend the validator whenever a new documentation rule should apply consistently rather than relying on memory during review.

How to confirm it is working

Section titled “How to confirm it is working”

The reliable proof for Update and Validate Documentation is the observable result described above. Reproduce it with a realistic example; if only the admin screen changed, continue tracing the workflow until the visitor or connected system sees the intended effect.

Practical example

Section titled “Practical example”

If a new upload type is added, trace MIME validation, size, upload, OpenAI attachment, states, preview/removal, then update four artifacts and tests.

Section titled “Recommended practice”
  • Change one part of Update and Validate Documentation at a time and keep a short record of the previous value and test result.
  • Verify the saved result in the screen, visitor session, or connected service that actually consumes the setting.

Important warnings

Section titled “Important warnings”

Common problems and focused checks

Section titled “Common problems and focused checks”
Common problems and focused checks
ProblemWhat to check and what to do next
Update and Validate Documentation is missing or does not match this guide. Confirm the plugin is active and the account can manage WordPress options. Regenerate source-derived files and run the complete documentation validation before publishing the result.
A change on Update and Validate Documentation does not produce the expected result. Keep the exact notice and test case, then review the browser console and WordPress/PHP log. Regenerate source-derived files and run the complete documentation validation before publishing the result.

Commands

Section titled “Commands”

Regenerate and validate

Section titled “Regenerate and validate”
npm run generate
npm run validate:all

Check for ungenerated catalog changes

Section titled “Check for ungenerated catalog changes”
npm run generate
git diff --exit-code -- src/content/docs audit/screenshot-inventory.md

Screen reference

Section titled “Screen reference”
Update and Validate Documentation
Capture
Show a code review with a feature matrix row, matching rendered page, and successful validation output; redact repository remotes/usernames.
Show
Matrix evidence, catalog change, rendered page, validation success
Viewport
Desktop, 1440 × 900
Annotate
Use numbered callouts only for controls referenced in the procedure.
Redact
OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text
Section titled “Related guides”