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.
[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:
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.