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:

Add to table of contents if significant Create new section with clear heading Include usage examples with code blocks Explain the "why" not just the "how" Configuration Guide Updates

Location: docs/CONFIGURATION.md

For new config options:

Add to the relevant section Show the TOML syntax Document the default value Explain what it does and when to use it

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

[section]
option = "value"

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:

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:

/// 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.