81 lines
8.8 KiB
Markdown
81 lines
8.8 KiB
Markdown
------
|
||
title: "07/17 Tl.1 用 AI 写文档不得不注意的几点……"
|
||
date: 2026-07-17 23:00:00
|
||
tags: [Thinklog, Skills]
|
||
categories: [Thinklog]
|
||
------
|
||
众所周知，现在的 AI 可谓是十分甚至有百分的强大，吉米 K3、被 A\ Ban 完了的 Fable 5 和 Tibo 爷爷日常重置额度让你猝不及防的 5.6 Sol 打的有来有回，GLM 5.2、DS 4 还在发力的现在，用 AI 写文档应该很简单……吗？
|
||
|
||
诶你要这样想那就不对了。让我们来看看一个例子，开源的 Rime 配置 **万象拼音** 的[文档](https://amzxyz.github.io/rime-wanxiang/doc/intro/)（基于CC-BY 4.0 获得许可）：
|
||
|
||
> 🛡️ 理念边界与开发者寄语
|
||
> 万象致力于夯实 Rime 生态中的“基础底座”。但为了避免您的预期偏差，我们必须坦诚地说明本项目“不做什么”：
|
||
>
|
||
> 关于学习成本的郑重声明
|
||
>
|
||
> 这里没有输入法基础教学：本项目不负责教您“如何记忆小鹤双拼键位”或“什么是五笔字根”。掌握双拼和辅助码是您提升效率的必经之路，这需要您在兴趣的驱动下自行调研与练习。
|
||
> 不提供保姆级 Rime 扫盲：全网已有海量关于 Rime 引擎基础配置的优秀教程。使用万象需要您具备最基础的折腾精神和软件认知能力。
|
||
> 我们将把所有有限的精力，持续聚焦于优化模型算法、提纯优质词库，力求在底座层面为您提供最坚实的后盾。
|
||
|
||
为什么虽然感觉词句很正常，但是这段文字仍然有浓烈的「AI 味」呢？原因有以下几点。
|
||
|
||
- 一就是 Emoji。这是 AI 写文档最致命的缺点：即使它会写 VuePress/VitePress 这样的文档模板库，但是它还是会用 Emoji，而不是用文档模板里的 Icon（Lucide 这些）。
|
||
- 二就是一个个的列条目。说实话我这样用 `-` 来举例也是一种行为，所以不得不说我的说话习惯已经被 AI 深刻影响了，要不然怎么我 Q 昵称是「豆包智能助手」呢（笑）。但是你就看原文里「这里没有……」「不提供……」是不是列条目吧……
|
||
- 三就是 AI 式句式。很明显现在 AI 发展趋势是往「会写代码」走，而不是「会说人话」走的。网上 AI Slop 水文越来越多，这些新 AI 在抓训练语料的时候肯定是会抓到越来越多它们同行写的文章的……再加上后期的 Tuning 和每个 AI IDE 里给的质量参差不齐的 Prompt，「不是而是」「诚实的」「致力于」「持续聚焦于」这些词就越来越不像一个正常人写出来的东西了。
|
||
- 四就是忽远忽近的距离。这里的「距离」指的是与读者建的距离或者换种方式说就是语言的亲和力。「坦诚地说明」「兴趣的驱动下」「折腾精神」「坚实后盾」这些偏「日常」（好吧有些并不是那么日常）的描述很明显就是拉近与读者之间的距离（冷知识这不是语文阅读理解），但与此同时，「优化模型算法」「软件认知能力」这些专业描述甚至专业人员都不一定看得懂的描述（我猜「软件认知能力」接近于「媒介素养」，但很明显我懒得查）造就了距离的不统一。
|
||
|
||
如果要一个一个列举这篇文章的长度会接近 ℵ_0，就算是 AI 也不能在有尽的时间内给它写出来，更何况用 AI 批斗 AI 何不就是一种 *极大的讽刺* ，所以我就写到这里为止。
|
||
|
||
那么，如果你就是懒，不想手写文档，又像我一样对 AI Slop 有着很大的厌恶（你猜我现在用不用万象拼音了），那么你该怎么办呢？
|
||
|
||
继续读下去。
|
||
|
||
（我不行了虽然单独成段十分有九分的蕴含 AI 风味但是我居然就给他写下来了，完了人类要䛃咭墢灗了😰）
|
||
|
||
首先，如果你是 API 库或者是造轮子类开发者，你可以尝试不单独写文档而是用自包含文档。用 Python 语言举例：
|
||
|
||
```python
|
||
def some_func(some_args: list[SomeType]) -> SomeType:
|
||
"""
|
||
一个函数。
|
||
|
||
Args:
|
||
some_args (SomeType): 一群用来啪啪啪的参数。
|
||
Returns:
|
||
SomeType: 对参数进行啪啪啪处理后的值。
|
||
Raises:
|
||
SomeError: 参数啪啪啪失败会引发此错误。
|
||
"""
|
||
```
|
||
|
||
这里我们采用了 Google 的 Python Docstring 规范。它既适用于直接阅读，也可以让类似 Sphinx 这些文档构建器读取格式并生成静态页面，供你部署到网站上。
|
||
|
||
诶但这里就有人要说了，MM 说半天还要我自己写。哎确实，但一个聪明的具有上下文阅读能力的行内补全其实就能完成此操作，何乐而不为呢？诶有有人要说了，MM 说半天还要我自己配置构建。你个老傻子（无恶意），你都用 AI 了，不会给 Agent 开 Computer Use 让它自己配置去？（哦对了记得分我点 Token。）
|
||
|
||
诶但这里又又又有人要说了，MM 我写的不是 **面向开发者的** 文档而是 **面向用户的**使用手册怎么办？（细节不是而是句型）诶，那我这里有点建议就可以给你了。
|
||
|
||
- **鉴于新的模型不说人话，为何不用老模型？** 像 Claude 3 / Gemini 2.5 Pro 这些模型都是被验证了文风很好的模型，有条件自然可以用。（当然别用 GPT。）此外，虽然 DeepSeek 常备认作是「文科生」，但鉴于它幻觉率确实是居高不下，我也不推荐你用 DeepSeek 写文档。毕竟有用户质问你「为什么它不工作」而你又不能指责它没看文档这就尴尬了对吧。
|
||
- **一定要告诉你的模型配图。** 既然是使用手册，那么配图自然是极好的。我说白了，即使你是（科普）书作家，不配图你的书肯定也卖不出去几本，特别有名的除外。（没错我就这么说了。）图只能是你自己截图了，最好还是你自己插入图，除非你的模型多模态很强，知道你软件截图在说的是什么。
|
||
- **不行就上风格提示词。** 这里要注意：虽然风格提示词本意是好的，但仍有几率你的模型读了之后胡言乱语不知道在说什么，而且你的 Token 用量也会暴涨。这里感谢 [再谈 LLM 辅助写作 - 少数派](https://sspai.com/post/110102) 这篇文章，包括风格提示词在内的许多东西都是直接或间接取材于此。如果你需要更多解决方案，可以看文末的 **扩展阅读**。
|
||
```
|
||
你是一个有边界感的助手，你不会在与用户的交谈中额外询问用户「你是否还要我做什么」「你是否还对什么感兴趣」。
|
||
|
||
你是一个负责责任的助手，你不会在答案中掺杂你的思考过程，你会想好再回答。你不会给用户提供好几个备选方案让用户自己挑，你会直接给出你认为最有信心的答案。
|
||
|
||
在回复用户任何答案之前，你都会认真搜索，你的所有答案必须言之有据，不可以有任何猜测的成分。
|
||
|
||
你不会使用根本性、结构性这两个词，你不会使用不是、而是句法或者任何隐喻拉踩的表达方式，你也不会写出任何此类表达的变体，像是「是，而非」。你不会使用破折号、插入语。你不会使用 ai 腔，如：这个问题是真实的、这件事的本质是、这是诚实的，或者自造生僻词汇，如「根因」。
|
||
```
|
||
- **告诉 AI 活用平台功能。** 你总不会一直都只用纯文本写文档，大多数时候，写作平台都是支持 Markdown（这也是 AI 所擅长的），附加一些特殊语法的。用 GitHub 来举例：
|
||
```markdown
|
||
> [!NOTE]
|
||
> Some Notes
|
||
```
|
||
是会有不同的样式的，因为 GitHub 扩展了 Markdown 语法，取名叫 *GitHub Favoured Markdown* 。VxxPress 也一样，甚至如果你换了 VxxPress 的主题，主题里也有特定语法。这样 AI 写作的时候就不会有 Emoji 泛滥的情况，但可能还是会出现——所以建议把「永远不输出 Emoji」写进 `AGNETS.md` 里面。
|
||
- **一定要有人工审核。** 停，我知道你在想什么，但是既然 OMI 在 Vibing 这件事上始终坚持 **「你不看所有代码至少也仔细看一遍核心代码」** 的观点，我们就建议你也看一遍文档，毕竟这不费脑子而且你的用户最终也得看这个，所以为什么不趁早修掉那些语句不通或者逻辑不对的句子，再稍微补全一点 AI 可能没写到的细节功能呢？
|
||
|
||
以上就是全文了。如果你想了解更多，除了文中所给的链接，我还建议你去少数派读读 [这个](https://sspai.com/post/109288) 和 [这个](https://sspai.com/post/111975)，写的都很有深度，我受益匪浅。当然，这篇文章肯定也有许多不完美的地方，作为抛砖引玉，希望能带给你更多的思考，也欢迎你在论坛发表高见。
|
||
|
||
这篇文章将会是 OhMyIWB 第一篇写给学生开发者的非 Daily 长文，我想就叫它 OhMyIWB Thinklog 吧。原有的 OhMyIWB 会继续更新，那么……
|
||
|
||
这里是 OMI，欢↗迎↘下↝次↘光↗临-~ |