Improving The LLM Wiki Setup Wizard And Public Guidance - Source Excerpt 04 - Roadmap and risk control
Back to Improving The LLM Wiki Setup Wizard And Public Guidance
Summary
This source excerpt begins near Roadmap and risk control and preserves the surrounding evidence from Wiki.FFTAC.org/agent-file-handoff/Archive/2026-05-11-improvement-concept-layer/Improving the LLM Wiki Setup Wizard and Public Guidance.md.
**Source path:** Wiki.FFTAC.org/agent-file-handoff/Archive/2026-05-11-improvement-concept-layer/Improving the LLM Wiki Setup Wizard and Public Guidance.md
The **single most important content change** is to rewrite the public guidance to front-load outcome language. The current site often explains what an LLM Wiki is in conceptually correct but architecture-heavy terms. New users need a clearer promise: what problem this solves, what file/folder or site they will have at the end, how long the setup takes, what is optional, and what the system will not do automatically. The best-performing documentation products are unusually clear about this kind of boundary language. GitBook’s redirect docs, WordPress’s permalink docs, and MediaWiki’s install docs are all direct, procedural, and explicit about side effects. citeturn4view2turn4view1turn33search1turn32search1turn34search11
The **single most important technical change** is to formalize the URL and canonical model. Handbook pages should self-canonicalize on LLMWikis. Provenance or recovered-source pages on wiki.fftac.org should either self-canonicalize as provenance records or canonicalize/noindex toward the relevant handbook page when intent overlaps. The metadata standard should explicitly include canonical URLs, descriptions, page types, and localization fields. Google’s guidance is clear that title links, meta descriptions, breadcrumbs, canonical URLs, and multilingual handling all depend on machine-readable consistency, not just good prose. citeturn0search1turn0search2turn0search3turn4view3turn30search0turn30search1turn30search2turn30search3turn30search6
The following mermaid flow shows the recommended wizard structure.
' ' ' mermaid
flowchart TD
A[Welcome] --> B[Choose your goal]
B --> C1[Personal wiki]
B --> C2[Team handbook]
B --> C3[Migrate existing docs]
B --> C4[Evidence archive]
C1 --> D[Name and location]
C2 --> D
C3 --> D
C4 --> D
D --> E[Audience and first sections]
E --> F[Preview starter structure and URLs]
F --> G{Need advanced options?}
G -->|No| H[Review packet]
G -->|Yes| I[Advanced options]
I --> I1[Permissions and review]
I --> I2[Migration and redirects]
I --> I3[Graph and export]
I --> I4[Handoff and intake]
I1 --> H
I2 --> H
I3 --> H
I4 --> H
H --> J[Export packet]
H --> K[Fix warnings]
K --> H
' ' '
That flow operationalizes the main benchmark lesson: **first produce a visible, useful plan; only then let the user deepen it**. citeturn29search1turn29search2turn27search0turn20view1turn20view0
A simple wireframe for the public wizard page should also change how the page feels. Right now, too much context appears before the user makes a first meaningful choice. The target state should look more like this.
' ' ' mermaid
flowchart TB
subgraph Page
A[Header with one primary nav]
B[Page title + one-sentence promise]
C[Progress bar]
D[Question panel]
E[Inline help and examples]
F[Sticky summary panel]
G[Validation / warnings]
H[Primary action]
end
A --> B --> C --> D --> E --> G --> H
D --> F
E --> F
G --> F
' ' '
The right-hand summary panel should not repeat the entire eventual packet. Instead, it should answer four questions in real time: **what you are setting up, where it will live, what defaults are active, and what still needs a choice**. That is a better fit for both mobile and desktop than the current model of exposing so much of the packet and AI digest inline on the same long page. citeturn5view2turn35view3turn29search0turn29search4
Concrete copy rewrites should accompany the structural changes. The examples below are intentionally conservative so they can be adopted without changing the underlying product position.
| Surface | Current direction | Recommended rewrite |
|---|---|---|
| Wizard intro | “Choose a setup path, answer one step at a time…” | **Plan your LLM Wiki in a few guided steps.** Start with your goal, preview the structure and URLs we recommend, then export a setup packet you can review before making any repository or site changes. |
| First question | “Choose setup path” | **What are you trying to set up?** Choose the closest starting point. You can refine the structure later. |
| Preset card | “Existing docs” | **Migrate existing docs** — Turn a current documentation set into a reviewable LLM Wiki without replacing your source files. |
| Advanced branch | “Add Project Handoff alignment” | **Need hot-context handoff too?** Add Project Handoff only if you need portable working context alongside the durable wiki. |
| Validation copy | not publicly visible | **Enter a wiki root URL or local path.** Example: `https://docs.example.com/llm-wiki/` or `/projects/acme/wiki/`. |
| Blocked export | not publicly visible | **You can’t export yet.** Add a wiki location and a review owner first, then try again. |
| Packet heading | “Generated setup packet” | **Your setup plan** — Review this summary before using it in a handoff, issue, or implementation checklist. |
Those rewrites align the public language with how successful documentation tools frame user value: short promise, narrow first choice, clear defaults, and plain-language constraints. citeturn17view0turn20view1turn33search19turn34search11
Finally, the public handbook should adopt a clearer **metadata and structured-data contract**. The current standard properly emphasizes ownership, review state, sensitivity, and agent use, but it should be expanded with web-facing fields like `seo_title`, `meta_description`, `canonical_url`, `page_type`, `primary_category`, `tags`, `locale`, and `schema_type`. This is one of the few changes that improves search visibility, internal retrieval, and editorial governance at the same time. citeturn4view3turn30search0turn30search1turn30search3turn30search6
## Roadmap and risk control
Because no budget or hard timeline was specified, the roadmap below is phased by dependency rather than calendar date. The effort estimates are relative.
| Phase | Milestones | Effort | Primary success metrics |
|---|---|---|---|
| Foundation | Freeze the public content model; define handbook vs provenance ownership; inventory all public URLs; map current pages to page types; instrument baseline analytics events. | Medium | Baseline captured for wizard starts, packet exports, exit rate, search queries, search zero-results, 404s, top landing pages. |
| Public guidance cleanup | Rewrite homepage hero, Start Here, Setup Wizard intro, and key standards pages; reduce repeated nav chrome; add stronger breadcrumbs and related-page modules; repair sitemap/discovery consistency. | Medium | Lower bounce on top landing pages; higher click-through from homepage to Start Here and Wizard; reduction in 404s and crawl issues. |
| Wizard MVP redesign | Ship preset-based wizard with five core steps, advanced branches, validation, review panel, and clearer export states; keep local draft support but improve recovery and warnings. | High | Higher wizard completion rate; lower median time to first packet; fewer exits on first two steps; fewer abandoned sessions after first interaction. |
| Technical hardening | Add explicit canonical/meta-description/page-type fields; implement structured breadcrumbs; test redirects; add accessibility QA for keyboard, labels, and reflow; measure CWV/Lighthouse internally. | Medium | Fewer indexing anomalies; improved title/snippet quality; fewer accessibility defects; improved mobile completion. |
| Search and content analytics | Add search analytics, zero-result capture, packet-export telemetry, and search-to-page success reporting; review content gaps monthly. | Medium | Reduced zero-result rate; higher search success; improved organic CTR on handbook pages. |
| Internationalization readiness | Add locale field, language switcher architecture, hreflang-ready routing, and translation workflow design; ship English-first with ready scaffolding before translating. | High | Locale-safe URL model in place; no auto-redirect traps; translation pilot can launch without URL rework. |
The roadmap sequence is deliberately front-loaded toward **content and structure**, because those changes have the highest leverage and the lowest rollback cost. A public wizard redesign without an agreed content model would likely recreate the current problem in a cleaner UI. By contrast, once page types, canonical ownership, and the URL/metadata contract are fixed, the wizard can generate far better defaults automatically. citeturn4view3turn33search3turn33search10turn30search1turn30search2