Skip to content
Skills Library
Programming · Writing

update-docs

/update-docs

Update voxtype documentation for releases and features. Use when adding features, fixing bugs, or preparing releases. Covers user manual, troubleshooting, website, release notes, and contributor credits.

Repository
voxtype ↗
Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Update voxtype documentation for releases and features. Use when adding features, fixing bugs, or preparing releases. Covers user manual, troubleshooting, website, release notes, and contributor credits.

Original author description

Update voxtype documentation for releases and features. Use when adding features, fixing bugs, or preparing releases. Covers user manual, troubleshooting, website, release notes, and contributor credits.

How it works

  1. Documentation Locations
  2. Writing Style
  3. User Manual Updates
  4. Configuration Guide Updates
  5. Troubleshooting Updates
  6. Website News Articles
  7. GitHub Release Notes
  8. Obsidian Vault Notes
  9. Crediting Contributors
  10. Release Documentation Checklist
Original SKILL.md headings · 186 lines, 608 words
SKILL.md preview
---
name: update-docs
description: Update voxtype documentation for releases and features. Use when adding features, fixing bugs, or preparing releases. Covers user manual, troubleshooting, website, release notes, and contributor credits.
user-invocable: true
allowed-tools:
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Bash
  - Skill
---

# Update Documentation

Guide for updating voxtype documentation across all locations.

## Documentation Locations

| Document | Location | When to Update |
|----------|----------|----------------|
| User Manual | `docs/USER_MANUAL.md` | New features, usage changes |
| Configuration Guide | `docs/CONFIGURATION.md` | New config options |
| Troubleshooting | `docs/TROUBLESHOOTING.md` | New error conditions, fixes |
| FAQ | `docs/FAQ.md` | Common questions |
| README | `README.md` | Major features, installation changes |
| Website News | `website/news/index.html` | Every release |
| GitHub Release | GitHub Releases | Every release |
| Obsidian Vault | `~/Documents/markdown-notes/Voxtype/` | Session notes, decisions |

## Writing Style

**Avoid AI writing patterns:**
- No em-dashes (—) - use colons or separate sentences
- No "delve", "leverage", "utilize", "streamline", "robust", "seamless"
- No excessive hedging ("It's worth noting...", "Interestingly...")
- No punchy one-liners ("And that's the point.", "Simple as that.")
- No sentence fragments for effect ("The result? Faster builds.")
- Write plainly and directly

## User Manual Updates

Location: `docs/USER_MANUAL.md`

When adding a feature:
1. Add to table of contents if significant
2. Create new section with clear heading
3. Include usage examples with code blocks
4. Explain the "why" not just the "how"

## Configuration Guide Updates

Location: `docs/CONFIGURATION.md`

For new config options:
1. Add to the relevant section
2. Show the TOML syntax
3. Document the default value
4. Explain what it does and when to use it

```markdown
### new_option

Enable the new feature.

```toml
[section]
new_option = true  # default: false
```

When enabled, this does X which is useful for Y.
```

## Troubleshooting Updates

Location: `docs/TROUBLESHOOTING.md`

Format for new issues:

```markdown
### Error: The specific error message

**Cause:** Why this happens

**Solution:**
1. Step one
2. Step two

**Example:**
```bash
command to fix
```
```

## Website News Articles

Location: `website/news/index.html`

Every GitHub release needs a matching news article. Follow v0.4.10/v0.4.11 as examples.

Structure:
```html
<article class="news-article" id="v0415">
    <div class="article-meta">
        <time datetime="2026-01-20">January 20, 2026</time>
        <span class="article-tag">Release</span>
    </div>
    <h2>v0.4.15: Feature Summary</h2>
    <div class="article-body">
        <p>Intro paragraph...</p>

        <h3>Feature Name</h3>
        <p>Description.</p>
        <p><strong>Why use it:</strong> User benefit.</p>

        <div class="code-block">
            <div class="code-header"><span>config.toml</span></div>
            <pre><code>[section]
option = "value"</code></pre>
        </div>
    </div>
</article>
```

Add new articles at the TOP of the articles list.

## GitHub Release Notes

Format:
- Title: `v0.4.15: Feature Summary`
- Brief intro paragraph
- `###` sections for each feature
- `**Why use it:**` callouts
- Bug fixes as bullet list
- Downloads table with checksums

## Obsidian Vault Notes

Use the `/obsidian` skill to save session context.

Location: `~/Documents/markdown-notes/Voxtype/`

Include:
- Summary of work completed
- Key decisions and rationale
- Links to PRs/issues
- Next steps

## Crediting Contributors

### In Commits

Add co-authors to commit messages:
```
Co-authored-by: Name <email@example.com>
```

### In Cargo.toml

Add to the authors array:
```toml
authors = [
    "Peter Jackson <pete@peteonrails.com>",
    "Contributor Name <contributor@example.com>",
]
```

### In README

Add to Contributors section with GitHub profile link.

### On Website

Add to the website's contributors or about page if significant contribution.

## Release Documentation Checklist

- [ ] Update `docs/USER_MANUAL.md` for new features
- [ ] Update `docs/CONFIGURATION.md` for new options
- [ ] Update `docs/TROUBLESHOOTING.md` for new error conditions
- [ ] Add news article to `website/news/index.html`
- [ ] Create GitHub release with notes
- [ ] Update `packaging/arch-bin/voxtype-bin.install` post_upgrade message
- [ ] Credit contributors in Cargo.toml and README
- [ ] Save session notes to Obsidian vault

## CLI Help Text

When adding new CLI options, update the clap attributes in `src/cli.rs`:

```rust
/// Clear description of what this option does
#[arg(long, short = 'x')]
pub new_option: bool,
```

The `--help` output IS documentation. Make it clear and complete.

Versions

RepositoryScoreLicence
This page · peteonrails/voxtype100MIT
iuliandita/skills100MIT
benweese/playwright-ai-qa-agents100MIT
thefrederiksen/devthrottle100MIT
vercel/next.js100MIT
RubenGlez/rubstack100MIT
tesseron-dev/tesseron100Apache-2.0
tmj-90/gaffer100Apache-2.0
navapbc/digital-service-orchestra100Apache-2.0

Database snapshot: 13.11.2026 · package version d1a8c7558ce7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100docs-update
    Use when the user needs to update, improve, audit, or maintain documentation in a project. Covers READMEs, changelogs, API docs, inline comments, missing docs, and overall documentation quality. Works well before releases or when documentation has fallen behind the code.
  • 100documentation-updater
    Update all project documentation including implementation docs, user guides, API docs, and architecture diagrams. Use when finalizing features to ensure comprehensive documentation.
  • 100documentation-management
    Operating manual for documentation work in nexus-agents. Use when updating docs, adding new docs, changing doc pipeline, or troubleshooting doc issues. Triggers on "update docs", "add documentation", "doc pipeline".
  • 100nvidia-nemoclaw-contributor-update-docs
    Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages and refresh generated user skills for release prep. Use when docs have fallen behind code changes, after a batch of features lands, during daily…
  • 100creating-releases-json
    Create or update a releases.json manifest so registries and agents can find where a company or project publishes its release notes. Use this whenever someone wants to "list our product on Releases", "add a releases.json", "get indexed on Releases Index", "here's our website,…
  • 100writing-release-notes
    Use when preparing, refreshing, backfilling, or redrafting a release-notes page under docs/releases/ before opening a normal review pull request.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.