update-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Documentation

更新文档

Guide for updating voxtype documentation across all locations.

全渠道更新voxtype文档的指南。

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

文档类型	位置	更新时机
用户手册	`docs/USER_MANUAL.md`	新增功能、使用方式变更
配置指南	`docs/CONFIGURATION.md`	新增配置选项
故障排查	`docs/TROUBLESHOOTING.md`	新增错误场景、修复方案
常见问题	`docs/FAQ.md`	出现高频问题时
README	`README.md`	重大功能更新、安装流程变更
网站资讯	`website/news/index.html`	每次版本发布时
GitHub版本说明	GitHub Releases	每次版本发布时
Obsidian知识库	`~/Documents/markdown-notes/Voxtype/`	记录会话笔记、决策内容

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

避免AI写作范式：

不要使用破折号（—），改用冒号或拆分句子
禁用"delve"、"leverage"、"utilize"、"streamline"、"robust"、"seamless"这类词汇
避免过度铺垫（如"值得注意的是..."、"有趣的是..."）
不要使用故作简洁的短句（如"这就是关键。"、"就这么简单。"）
不要为了效果使用不完整的句子（如"结果？构建速度更快。"）
语言直白、直接

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"

位置：

docs/USER_MANUAL.md

添加新功能时：

若功能重要，需添加到目录
创建带有清晰标题的新章节
包含带有代码块的使用示例
不仅说明“怎么做”，还要解释“为什么这么做”

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

markdown

undefined

位置：

docs/CONFIGURATION.md

新增配置选项时：

添加到对应章节
展示TOML语法示例
记录默认值
说明功能作用及适用场景

markdown

undefined

new_option

Enable the new feature.

toml

[section]
new_option = true  # default: false

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

undefined

启用新功能。

toml

[section]
new_option = true  # default: false

启用后，该选项会实现X功能，适用于Y场景。

undefined

Troubleshooting Updates

故障排查更新

Location:

docs/TROUBLESHOOTING.md

Format for new issues:

markdown

undefined

位置：

docs/TROUBLESHOOTING.md

新增问题的格式：

markdown

undefined

Error: The specific error message

错误：具体错误信息

Cause: Why this happens

Solution:

Step one
Step two

Example:

bash

command to fix

undefined

原因： 问题出现的诱因

解决方案：

步骤一
步骤二

示例：

bash

修复命令

undefined

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.

位置：

website/news/index.html

每次GitHub版本发布都需要同步添加对应的资讯文章。可参考v0.4.10/v0.4.11的格式。

结构：

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>引言段落...</p>

        <h3>Feature Name</h3>
        <p>描述内容。</p>
        <p><strong>Why use it:</strong> 用户收益。</p>

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

新文章需添加到资讯列表的顶部。

GitHub Release Notes

GitHub版本说明

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

格式要求：

标题：
```
v0.4.15: Feature Summary
```
简短的引言段落
每个功能对应一个
```
###
```
章节
包含
```
**Why use it:**
```
标注
漏洞修复以项目符号列表呈现
包含校验和的下载表格

Obsidian Vault Notes

Obsidian知识库笔记

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

使用

/obsidian

技能保存会话上下文。

位置：

~/Documents/markdown-notes/Voxtype/

需包含：

已完成工作的摘要
关键决策及理由
关联PR/问题的链接
下一步计划

Crediting Contributors

贡献者署名

In Commits

提交记录中

Add co-authors to commit messages:

Co-authored-by: Name <email@example.com>

在提交信息中添加协作者：

Co-authored-by: Name <email@example.com>

In Cargo.toml

Cargo.toml中

Add to the authors array:

toml

authors = [
    "Peter Jackson <pete@peteonrails.com>",
    "Contributor Name <contributor@example.com>",
]

添加到authors数组：

toml

authors = [
    "Peter Jackson <pete@peteonrails.com>",
    "Contributor Name <contributor@example.com>",
]

In README

README中

Add to Contributors section with GitHub profile link.

添加到贡献者章节，并附上GitHub个人主页链接。

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

针对新功能更新
```
docs/USER_MANUAL.md
```
针对新选项更新
```
docs/CONFIGURATION.md
```
针对新错误场景更新
```
docs/TROUBLESHOOTING.md
```
向
```
website/news/index.html
```
添加资讯文章
创建带有说明的GitHub版本发布
更新
```
packaging/arch-bin/voxtype-bin.install
```
中的post_upgrade提示信息
在Cargo.toml和README中署名贡献者
将会话笔记保存到Obsidian知识库

CLI Help Text

CLI帮助文本

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.

添加新CLI选项时，更新

src/cli.rs

中的clap属性：

rust

/// 该选项功能的清晰描述
#[arg(long, short = 'x')]
pub new_option: bool,

--help

的输出属于文档范畴，需确保内容清晰、完整。