zensical-docs skills started

2026-06-18 22:33:19 -05:00
parent 818de1b3f9
commit a4db33531e
5 changed files with 387 additions and 0 deletions
@@ -0,0 +1,153 @@
 ---
 name: zensical-docs
 description: 'Plan, write, and improve high-quality documentation with Zensical. Use for information architecture, progressive discoverability, writing standards, navigation/search tuning, and feature-driven docs site configuration.'
 argument-hint: 'What are you documenting, who is the audience, and what Zensical features are in scope?'
 ---
 # Zensical Documentation Authoring
 Create documentation that is easy to discover, easy to scan, and easy to trust, then configure Zensical so the site reinforces those outcomes.
 ## When to Use
 - You are creating or restructuring docs in a Zensical project.
 - You need a repeatable workflow for docs quality and discoverability.
 - You want guidance that combines writing best practices with Zensical feature choices.
 - You need a checklist-driven review before publishing.
 ## Progressive Loading References
 Load only the references required for the current task:
 - Source map for official docs and APIs: [./references/index.md](./references/index.md)
 - Zensical features and configuration links: [./references/zensical-features.md](./references/zensical-features.md)
 - Docs writing quality and style guidance: [./references/documentation-quality.md](./references/documentation-quality.md)
 - Information architecture and discoverability patterns: [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md)
 ## Inputs To Collect
 Collect these before writing. If missing, make explicit assumptions.
 1. Audience: beginner, intermediate, advanced, or mixed.
 2. User goals: top tasks users come to complete.
 3. Product scope: features, versions, and deployment context.
 4. Content constraints: release deadlines, localization, legal/compliance needs.
 5. Navigation constraints: explicit `nav` vs implicit structure.
 6. Site-level expectations: search quality, code example depth, diagrams, API docs.
 ## Procedure
 ### Step 0: Audit Current Documentation
 Build a quick baseline of what exists now.
 1. List docs sections and current nav structure.
 2. Identify orphan pages (not in nav, weak internal linking, or no inbound links).
 3. Identify stale sections (version drift, missing prerequisites, broken commands).
 4. Capture recurring support questions and map each to a missing or weak doc page.
 Completion check: you can name the top 5 current documentation gaps.
 ### Step 1: Define Outcomes and Page Taxonomy
 Organize content by user intent, not by internal team boundaries.
 1. Split content into at least four buckets:
   - Learn (concepts and mental models)
   - Do (task/how-to guides)
   - Reference (API, config, CLI, schemas)
   - Troubleshoot (symptoms, diagnostics, fixes)
 2. For each bucket, define success criteria and expected time-to-answer.
 3. Add clear page entry criteria (what belongs here, what does not).
 Completion check: every planned page maps to one primary user intent.
 ### Step 2: Design Progressive Discoverability
 Make docs progressively discoverable from overview to detail.
 1. Start each section with an index/overview page that answers:
   - who this section is for
   - what problems it solves
   - where to go next
 2. Keep page openings front-loaded:
   - first paragraph states purpose and outcome
   - first heading after intro is usually prerequisites or quickstart path
 3. Add consistent wayfinding on every page:
   - links to prerequisite concepts
   - links to next steps
   - links to relevant reference sections
 4. Prefer short sections, descriptive headings, and stable anchor names.
 Completion check: users can navigate from high-level overview to exact procedure in 3 clicks or fewer.
 ### Step 3: Author High-Trust Content
 Use writing patterns that reduce ambiguity and failure.
 1. Use imperative, task-oriented titles (for example: "Configure SSO with OIDC").
 2. State assumptions and prerequisites before commands.
 3. Provide copy-paste-safe examples and expected outputs.
 4. Include rollback or recovery steps for risky operations.
 5. Separate normative guidance (must/should) from optional patterns.
 6. Call out version-specific behavior explicitly.
 Completion check: each task page includes prerequisites, steps, expected result, and failure recovery.
 ### Step 4: Apply Zensical Features Intentionally
 Load [./references/zensical-features.md](./references/zensical-features.md) and choose features based on content needs.
 Decision matrix:
 - If docs are deep and section-heavy: enable `navigation.indexes`, `navigation.path`, and `navigation.sections`.
 - If speed and perceived responsiveness matter: enable `navigation.instant` and `navigation.instant.prefetch`.
 - If code-heavy content exists: enable `content.code.copy`, `content.code.select`, and `content.code.annotate`.
 - If users rely on search often: enable `search.highlight` and improve heading quality for better snippets.
 - If many pages share tab labels (for example Python/JS): enable `content.tabs.link`.
 Completion check: each enabled feature has a documented rationale tied to a user outcome.
 ### Step 5: Standardize Navigation and Search Quality
 1. Use explicit nav for critical docs journeys and release-stable ordering.
 2. Keep page titles and H1 aligned with search intent language users actually type.
 3. Avoid duplicate page titles across sections.
 4. Use concise first paragraphs because search snippets often rely on early content.
 5. Add cross-links between concept, task, and reference pages.
 Completion check: top support queries return a correct page within first search results.
 ### Step 6: Publish and Validate
 1. Build the site: `uv run zensical build`
 2. Validate links, code blocks, and navigation paths.
 3. Review on desktop and mobile for scanability and heading rhythm.
 4. Check that key journeys (new user setup, common task, troubleshooting flow) are uninterrupted.
 Completion check: no broken links, no dead-end pages, and all critical journeys are complete.
 ## Completion Checks
 - Page taxonomy is intent-based: Learn, Do, Reference, Troubleshoot.
 - Every major section has an overview page and next-step links.
 - Task docs contain prerequisites, steps, expected results, and recovery guidance.
 - Enabled Zensical features are justified and aligned to user needs.
 - Navigation and search behavior are verified with real user tasks.
 - Site builds cleanly with `uv run zensical build`.
 ## Output Contract
 Return:
 1. Proposed docs architecture and navigation map.
 2. Zensical feature configuration recommendations with rationale.
 3. A prioritized writing backlog (must-have, should-have, nice-to-have).
 4. A quality-gate checklist for pre-publish review.
 ## Guardrails
 - Do not produce architecture-only docs without concrete task pages.
 - Do not bury prerequisites or version constraints below the fold.
 - Do not rely only on search; preserve strong navigational paths.
 - Do not enable features without documenting the expected user benefit.
@@ -0,0 +1,74 @@
 # Discoverability and Information Architecture
 Use this reference to design docs that are progressively discoverable from overview to implementation detail.
 ## IA Model
 Organize by user intent, then by product area.
 Recommended top-level model:
 1. Learn (concepts, architecture, mental models)
 2. Do (task/how-to paths)
 3. Reference (API, config, command catalog)
 4. Troubleshoot (symptoms, diagnostics, fixes)
 References:
 - Diataxis framework: https://diataxis.fr/
 - Divio documentation system: https://documentation.divio.com/
 ## Progressive Discoverability Pattern
 ### Layer 1: Section Overview
 Each section starts with an index page containing:
 - What this section is for
 - Who should read it
 - Common journeys
 - Links to key tasks and references
 ### Layer 2: Task or Concept Pages
 Each page includes:
 - 1-2 sentence purpose
 - prerequisites
 - internal links to references and next steps
 ### Layer 3: Deep Reference
 Keep deep details in dedicated reference pages and link to them from task pages when needed.
 ## Navigation Design Rules
 1. Keep navigation labels user-facing and action-oriented.
 2. Avoid duplicate labels in separate branches.
 3. Place high-frequency tasks near the top.
 4. Keep section depth shallow where possible.
 Relevant Zensical configuration docs:
 - Navigation: https://zensical.org/docs/setup/navigation/
 - Search: https://zensical.org/docs/setup/search/
 - Header: https://zensical.org/docs/setup/header/
 - Footer: https://zensical.org/docs/setup/footer/
 ## Link Strategy
 - Every deep page should have at least one inbound link from a higher-level index page.
 - Add "See also" blocks for neighboring tasks.
 - Link to source-of-truth reference pages instead of duplicating config tables.
 ## Search Optimization for Docs
 - Put key terms in title and first paragraph.
 - Use specific H2/H3 headings that match user query language.
 - Keep repeated boilerplate minimal so snippets stay informative.
 ## Review Heuristics
 A documentation journey is healthy when:
 - users can identify their path within 10 seconds on a section index page
 - users can complete primary tasks without opening more than 2-3 tabs
 - users can recover from common errors without external support tickets
@@ -0,0 +1,54 @@
 # Documentation Quality Best Practices
 Use this reference when writing or reviewing docs for clarity, correctness, and trust.
 ## Core Writing Principles
 1. Write for a specific audience and task.
 2. Lead with outcomes, not internal implementation details.
 3. Keep concepts, tasks, and references distinct.
 4. Make examples executable and verifiable.
 5. Prefer precise language over marketing language.
 Primary references:
 - Diataxis: https://diataxis.fr/
 - Divio documentation system: https://documentation.divio.com/
 - Write the Docs guide: https://www.writethedocs.org/guide/
 ## Style and Readability
 - Use consistent terminology and avoid synonym drift.
 - Use short paragraphs and meaningful headings.
 - Prefer active voice and imperative instructions for task pages.
 - Add notes/warnings only for high-impact caveats.
 Source links:
 - Google developer style: https://developers.google.com/style
 - Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
 - MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
 ## Task Page Quality Pattern
 Each task page should include:
 1. Goal and scope.
 2. Prerequisites (permissions, versions, environment).
 3. Step-by-step procedure.
 4. Expected result and verification command/output.
 5. Common failure modes and recovery path.
 6. Related links (concept, reference, troubleshooting).
 ## Quality Gates Before Publish
 - Accuracy: commands and code examples are validated.
 - Completeness: no critical missing steps.
 - Discoverability: page is linked from at least one overview page.
 - Freshness: version-specific notes and dates are present where needed.
 - Accessibility: heading structure and link text are clear.
 ## Anti-Patterns
 - Mixing conceptual explanation and long procedural flow in the same section without structure.
 - Hiding prerequisites mid-page.
 - Using screenshots as the only source of truth for commands.
 - Publishing pages with no owner and no review cadence.
@@ -0,0 +1,38 @@
 # Zensical Docs Skill References
 Use this index to load only the source references needed for the current task.
 ## Zensical Official Docs
 - Home: https://zensical.org/docs/
 - Setup basics: https://zensical.org/docs/setup/basics/
 - Navigation setup: https://zensical.org/docs/setup/navigation/
 - Header setup and announcement bar: https://zensical.org/docs/setup/header/
 - Footer setup: https://zensical.org/docs/setup/footer/
 - Repository and content actions: https://zensical.org/docs/setup/repository/
 - Search setup: https://zensical.org/docs/setup/search/
 - Customization overview: https://zensical.org/docs/customization/
 - Additional CSS: https://zensical.org/docs/customization/#additional-css
 - Additional JavaScript: https://zensical.org/docs/customization/#additional-javascript
 - Theme extension and overrides: https://zensical.org/docs/customization/#extending-the-theme
 - Language setup: https://zensical.org/docs/setup/language/
 - Logo and icons: https://zensical.org/docs/setup/logo-and-icons/
 - Code blocks and annotations: https://zensical.org/docs/authoring/code-blocks/
 - Content tabs: https://zensical.org/docs/authoring/content-tabs/
 - Footnotes: https://zensical.org/docs/authoring/footnotes/
 - Tooltips: https://zensical.org/docs/authoring/tooltips/
 ## Adjacent Documentation Quality Sources
 - Divio documentation system: https://documentation.divio.com/
 - Write the Docs guide: https://www.writethedocs.org/guide/
 - Google developer documentation style guide: https://developers.google.com/style
 - Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
 - MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
 - Diataxis framework: https://diataxis.fr/
 ## Related Tooling References
 - Markdown guide: https://www.markdownguide.org/
 - MkDocs configuration reference: https://www.mkdocs.org/user-guide/configuration/
 - Material for MkDocs setup reference: https://squidfunk.github.io/mkdocs-material/setup/
@@ -0,0 +1,68 @@
 # Zensical Features and Configuration Patterns
 Use this reference when deciding which Zensical features to enable and why.
 ## High-Value Feature Groups
 ### Navigation and Discoverability
 - `navigation.indexes`: lets sections have index pages for overview content.
 - `navigation.path`: adds breadcrumb-like context.
 - `navigation.sections`: groups top-level sections for large doc sets.
 - `navigation.instant`: enables instant internal navigation.
 - `navigation.instant.prefetch`: prefetches likely next pages.
 - `navigation.top`: shows a back-to-top affordance.
 - `navigation.tracking`: keeps URL anchors in sync with active section.
 Source links:
 - https://zensical.org/docs/setup/navigation/
 ### Code-Heavy Documentation
 - `content.code.copy`: copy button in code blocks.
 - `content.code.select`: line range selection support.
 - `content.code.annotate`: inline code annotations.
 Source links:
 - https://zensical.org/docs/authoring/code-blocks/
 ### Cross-Page UX Consistency
 - `content.tabs.link`: keeps same-named tabs synchronized.
 - `content.tooltips`: improves tooltip behavior for links.
 - `content.footnote.tooltips`: inline footnote previews.
 Source links:
 - https://zensical.org/docs/authoring/content-tabs/
 - https://zensical.org/docs/authoring/tooltips/
 - https://zensical.org/docs/authoring/footnotes/
 ### Search and Content Actions
 - `search.highlight`: highlights matches after search navigation.
 - `content.action.edit` and `content.action.view` (if repository integration is configured).
 Source links:
 - https://zensical.org/docs/setup/search/
 - https://zensical.org/docs/setup/repository/
 ## Styling and Extensibility
 Use site-level customization when docs need stronger visual affordances.
 - `extra_css`: add targeted style overrides.
 - `extra_javascript`: add behavior enhancements.
 - Theme override directory (`custom_dir`) for template-level changes.
 Source links:
 - https://zensical.org/docs/customization/
 - https://zensical.org/docs/customization/#additional-css
 - https://zensical.org/docs/customization/#additional-javascript
 - https://zensical.org/docs/customization/#extending-the-theme
 ## Practical Feature Selection Rules
 1. Start with discoverability and clarity features first.
 2. Add convenience features (copy/select/tooltips) when content type supports them.
 3. Avoid enabling many features at once without measurement.
 4. Track user success metrics (search success, time-to-answer, support deflection) after each change.