zensical-docs skills started
This commit is contained in:
John Lancaster
@@ -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.
|
||||
Reference in New Issue
Block a user