|
|
|
@@ -1,175 +1,95 @@
|
|
|
|
|
---
|
|
|
|
|
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.'
|
|
|
|
|
description: 'Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links, then edit this skill over time to record project preferences for when each feature should be used.'
|
|
|
|
|
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.
|
|
|
|
|
Use this as a compact reference for Zensical mechanics and as the place to record evolving preferences for how this repository uses them.
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
- You need a quick reminder of Zensical features, docs structure, or configuration mechanics.
|
|
|
|
|
- You want direct links back to source documentation before changing docs behavior.
|
|
|
|
|
- You want one small file you can keep editing as your preferences around docs authoring become clearer.
|
|
|
|
|
|
|
|
|
|
## Progressive Loading References
|
|
|
|
|
## How To Use This Skill
|
|
|
|
|
|
|
|
|
|
Load only the references required for the current task:
|
|
|
|
|
1. Start here for a quick decision about what kind of docs change you are making.
|
|
|
|
|
2. Open only the linked reference that matches the current task.
|
|
|
|
|
3. Add or revise preference notes in this file when you decide how this repo should use a feature.
|
|
|
|
|
|
|
|
|
|
- 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)
|
|
|
|
|
- Theme customization, colors, icons, and extension patterns: [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.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)
|
|
|
|
|
- Code-heavy API docs with mkdocstrings: [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md)
|
|
|
|
|
## Quick Reference Map
|
|
|
|
|
|
|
|
|
|
## Project Bootstrap Rule
|
|
|
|
|
Open only what you need:
|
|
|
|
|
|
|
|
|
|
Always start a new documentation project with `uv run zensical new`.
|
|
|
|
|
- Official docs and source map: [./references/index.md](./references/index.md)
|
|
|
|
|
- Zensical feature catalog and setup links: [./references/zensical-features.md](./references/zensical-features.md)
|
|
|
|
|
- Theme, icons, and visual customization: [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md)
|
|
|
|
|
- Writing quality and review criteria: [./references/documentation-quality.md](./references/documentation-quality.md)
|
|
|
|
|
- Navigation and discoverability patterns: [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md)
|
|
|
|
|
- Code-heavy docs and API reference patterns: [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md)
|
|
|
|
|
|
|
|
|
|
- This command provides the baseline scaffolding you need for structure, configuration, and theme setup.
|
|
|
|
|
- Do not hand-build a new project skeleton when this command is available.
|
|
|
|
|
## Common Cases
|
|
|
|
|
|
|
|
|
|
## Related Skill Discovery
|
|
|
|
|
### New docs project
|
|
|
|
|
|
|
|
|
|
When the task is not just writing docs but creating or wiring a new MCP skill in this repository, use catalog discovery to load the bootstrap skill before drafting implementation steps.
|
|
|
|
|
- Start with `uv run zensical new`.
|
|
|
|
|
- Then review [./references/index.md](./references/index.md) and [./references/zensical-features.md](./references/zensical-features.md).
|
|
|
|
|
|
|
|
|
|
1. Search the catalog with terms such as `new skill`, `skill bootstrap`, or `scaffold skill`.
|
|
|
|
|
2. Fetch the `new-skill` document through the catalog tool path.
|
|
|
|
|
3. Use that skill for runtime package, metadata, and mount wiring, then return here for documentation architecture and Zensical-specific authoring guidance.
|
|
|
|
|
### Restructuring docs or navigation
|
|
|
|
|
|
|
|
|
|
This keeps implementation guidance and documentation guidance separated while still making both discoverable from one request.
|
|
|
|
|
- Review [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md).
|
|
|
|
|
- Use it to decide overview pages, section structure, and cross-linking.
|
|
|
|
|
|
|
|
|
|
## Inputs To Collect
|
|
|
|
|
### Improving writing quality
|
|
|
|
|
|
|
|
|
|
Collect these before writing. If missing, make explicit assumptions.
|
|
|
|
|
- Review [./references/documentation-quality.md](./references/documentation-quality.md).
|
|
|
|
|
- Use it for page quality gates, trust signals, and review criteria.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
### Adjusting theme or UI mechanics
|
|
|
|
|
|
|
|
|
|
## Procedure
|
|
|
|
|
- Review [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md).
|
|
|
|
|
- Use it for icons, color, theme extensions, and presentation choices.
|
|
|
|
|
|
|
|
|
|
### Step 0: Audit Current Documentation
|
|
|
|
|
### Documenting APIs or code-heavy systems
|
|
|
|
|
|
|
|
|
|
Build a quick baseline of what exists now.
|
|
|
|
|
- Review [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md).
|
|
|
|
|
- Use it when generated API reference belongs alongside hand-authored docs.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
## Preferences To Maintain Here
|
|
|
|
|
|
|
|
|
|
Completion check: you can name the top 5 current documentation gaps.
|
|
|
|
|
Keep this section short and revise it over time.
|
|
|
|
|
|
|
|
|
|
### Step 1: Define Outcomes and Page Taxonomy
|
|
|
|
|
### Preferred feature choices
|
|
|
|
|
|
|
|
|
|
Organize content by user intent, not by internal team boundaries.
|
|
|
|
|
- Add the Zensical features you usually enable first.
|
|
|
|
|
- Note which features are situational and why.
|
|
|
|
|
- Prefer Zensical-native features and conventions when they cover the need cleanly.
|
|
|
|
|
- Expect general backward compatibility with MkDocs patterns and configuration unless there is a documented reason not to.
|
|
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
### Preferred docs structure
|
|
|
|
|
|
|
|
|
|
Completion check: every planned page maps to one primary user intent.
|
|
|
|
|
- Record whether this repo prefers explicit nav, index pages, task-first docs, or another pattern.
|
|
|
|
|
|
|
|
|
|
### Step 2: Design Progressive Discoverability
|
|
|
|
|
### Preferred API docs approach
|
|
|
|
|
|
|
|
|
|
Make docs progressively discoverable from overview to detail.
|
|
|
|
|
- Record whether to use mkdocstrings, how much API surface to publish, and how to link task docs back to reference pages.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
## Source-First Rule
|
|
|
|
|
|
|
|
|
|
Completion check: users can navigate from high-level overview to exact procedure in 3 clicks or fewer.
|
|
|
|
|
When making a recommendation, link back to the relevant reference file first, and when possible to the upstream docs linked from that reference.
|
|
|
|
|
|
|
|
|
|
### Step 3: Author High-Trust Content
|
|
|
|
|
## Compatibility Rule
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
Load [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md) when the docs include Python APIs or other generated references.
|
|
|
|
|
|
|
|
|
|
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 code-heavy content includes API references: standardize on mkdocstrings for generated API docs and keep hand-written task guides alongside generated reference pages.
|
|
|
|
|
- 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.
|
|
|
|
|
- Code-heavy documentation strategy is explicit, including when and how mkdocstrings is used.
|
|
|
|
|
- Navigation and search behavior are verified with real user tasks.
|
|
|
|
|
- Site builds cleanly with `uv run zensical build`.
|
|
|
|
|
Prefer the Zensical-native way of doing something when it exists and is well-supported.
|
|
|
|
|
Assume MkDocs compatibility is still expected for most configuration and authoring patterns, and call out any case where a Zensical recommendation intentionally diverges from standard MkDocs behavior.
|
|
|
|
|
|
|
|
|
|
## Output Contract
|
|
|
|
|
|
|
|
|
|
Return:
|
|
|
|
|
Return only what is useful for the current docs task:
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
1. Which reference to read next.
|
|
|
|
|
2. The smallest recommended docs or config change.
|
|
|
|
|
3. Any repo-specific preference this suggests should be added back into this skill.
|
|
|
|
|
John Lancaster