1 ） 结论：
2 ） 正文：
我经历的公司之一
很强调文档的建立
因为很多知识在员工的脑子里
准确的说，是前员工的脑子里
于是
当员工离开后
面对注释不多的代码
就要建立文档
各种构建说明，问题解决的问题
2.1 )
我之前会在自己私人项目的代码里
写一些自己的注释
很不规范，甚至啰嗦，甚至带有情绪（惊奇，疲倦，沮丧，生气）
但是我能懂我当时写注释的情景
理解我的困惑
标记代码线路
我的 git （一个代码版本管理软件） 提交 消息，也是很口语的
甚至带有无关故事和情绪的 提交 消息
这会让某些技术人员反感
2.2 )
不过有的公司要求“代码即注释”
也就是少写注释
因为担心注释赶不上代码的变化
这或许是有道理的
听说大公司华为就是这样的要求
于是，在那样的公司里，我不怎么写文档和注释
2.3 )
总之回到文档这一个话题
什么是好的文档呢
我觉得是让别人和自己都懂的文档就是好的文档
形式不那么重要
用pdf，word，markdown，用xx云笔记，typora，latex 都行
但是我想
最好的就是 txt
纯文本的威力是巨大的
你自己敲的每个字，是威力巨大的
文档模板看起来很重要
它规范的大家的思考路线
但是面对未知的时候，人们无法使用模板
而是只能打草稿
分析草稿上的信息
最后完成思维的演算
才能按照模板进行文档编写
可贵的是思考的过程
于是
草稿对我来说是重要的
它保留了你思考的轨迹细节
尽管你会走弯路
2.4 )
模板是站在楼顶的人的产物，而文档的阅读者，很有可能在第一层
我读到下面一段话：
“你不能自己站在11层上，然后假设你的读者站在第10层，指望着只要告诉他第11层有那些内容就让他明白。你的读者站在第一层，你必须知道你脚下踩着的另外10层到底是怎么构造的。这就迫使你对你所掌握的、或之前认为正确的那些东西作彻彻底底的、深刻的反思，你的受众越是不懂，你需要反思得就越深刻”
摘录来自 暗时间 刘未鹏
2.5 )
硕士期间，我和同学们会写论文
而论文是有标准模板的
第一章节 就是 介绍背景， introduction 部分
第二章 就是 方法， Method
然后 实验 ， experienment
最后 结论，展望啥的。 conclusion
本科期间
我讨厌论文
我对同学说：论文，就是不说人话
终究，我还是不说人话，才能硕士毕业呀
2.6 )
但是，我还是不爱看论文
我的偏见是：
论文是可恶的
科普的文章是好的
上面的红头文件是可恶的（官腔）
乡民自发的约定是好的（大白话）
所以暂时我的想法是
好的技术文档就是大白话
就是朗朗上口的口语表达
不要用太多术语
显得你很专业
2.7 ))
然后一个文档要小
围绕一个问题就好
不要大而全
一句话能说明问题
一句话能说明结论
不要堆切辞藻
不要过分在意 格式，图示的标题，左右对齐还是居中
2.8 )
你要在意的是：
这3点 就是我理解的 好的 技术文档的 标准；
---
附件实际上是 WindTerm_2.7.0_Mac_Portable_x86_64.dmg + 了 txt 后缀
","content_text":"1 ） 结论：\n\n * 谁会读你的文档，为你文档的受众考虑，爱护他们，选择他们能懂的表达方式\n * 思维要清晰，逻辑要简单\n * 及时更新你的文档，为了读者不接收错误的信息，而努力维护好文档\n\n2 ） 正文：\n\n我经历的公司之一\n\n很强调文档的建立\n\n因为很多知识在员工的脑子里\n\n准确的说，是前员工的脑子里\n\n于是\n\n当员工离开后\n\n面对注释不多的代码\n\n就要建立文档\n\n各种构建说明，问题解决的问题\n\n2.1 )\n\n我之前会在自己私人项目的代码里\n\n写一些自己的注释\n\n很不规范，甚至啰嗦，甚至带有情绪（惊奇，疲倦，沮丧，生气）\n\n但是我能懂我当时写注释的情景\n\n理解我的困惑\n\n标记代码线路\n\n我的 git （一个代码版本管理软件） 提交 消息，也是很口语的\n\n甚至带有无关故事和情绪的 提交 消息\n\n这会让某些技术人员反感\n\n2.2 )\n\n不过有的公司要求“代码即注释”\n\n也就是少写注释\n\n因为担心注释赶不上代码的变化\n\n这或许是有道理的\n\n听说大公司华为就是这样的要求\n\n于是，在那样的公司里，我不怎么写文档和注释\n\n2.3 )\n\n总之回到文档这一个话题\n\n什么是好的文档呢\n\n我觉得是让别人和自己都懂的文档就是好的文档\n\n形式不那么重要\n\n用pdf，word，markdown，用xx云笔记，typora，latex 都行\n\n但是我想\n\n最好的就是 txt\n\n纯文本的威力是巨大的\n\n你自己敲的每个字，是威力巨大的\n\n文档模板看起来很重要\n\n它规范的大家的思考路线\n\n但是面对未知的时候，人们无法使用模板\n\n而是只能打草稿\n\n分析草稿上的信息\n\n最后完成思维的演算\n\n才能按照模板进行文档编写\n\n可贵的是思考的过程\n\n于是\n\n草稿对我来说是重要的\n\n它保留了你思考的轨迹细节\n\n尽管你会走弯路\n\n2.4 )\n\n模板是站在楼顶的人的产物，而文档的阅读者，很有可能在第一层\n\n我读到下面一段话：\n\n“你不能自己站在11层上，然后假设你的读者站在第10层，指望着只要告诉他第11层有那些内容就让他明白。你的读者站在第一层，你必须知道你脚下踩着的另外10层到底是怎么构造的。这就迫使你对你所掌握的、或之前认为正确的那些东西作彻彻底底的、深刻的反思，你的受众越是不懂，你需要反思得就越深刻”\n\n摘录来自 暗时间 刘未鹏\n\n2.5 )\n\n硕士期间，我和同学们会写论文\n\n而论文是有标准模板的\n\n第一章节 就是 介绍背景， introduction 部分\n\n第二章 就是 方法， Method\n\n然后 实验 ， experienment\n\n最后 结论，展望啥的。 conclusion\n\n本科期间\n\n我讨厌论文\n\n我对同学说：论文，就是不说人话\n\n终究，我还是不说人话，才能硕士毕业呀\n\n2.6 )\n\n但是，我还是不爱看论文\n\n我的偏见是：\n\n论文是可恶的\n\n科普的文章是好的\n\n上面的红头文件是可恶的（官腔）\n\n乡民自发的约定是好的（大白话）\n\n所以暂时我的想法是\n\n好的技术文档就是大白话\n\n就是朗朗上口的口语表达\n\n不要用太多术语\n\n显得你很专业\n\n2.7 ))\n\n然后一个文档要小\n\n围绕一个问题就好\n\n不要大而全\n\n一句话能说明问题\n\n一句话能说明结论\n\n不要堆切辞藻\n\n不要过分在意 格式，图示的标题，左右对齐还是居中\n\n2.8 )\n\n你要在意的是：\n\n * 谁会读你的文档，为你文档的受众考虑，爱护他们，选择他们能懂的表达方式\n * 思维要清晰，逻辑要简单\n * 及时更新你的文档，为了读者不接收错误的信息，而努力维护好文档\n\n这3点 就是我理解的 好的 技术文档的 标准；\n\n\n\n\n---\n\n\n\n\n附件实际上是 WindTerm_2.7.0_Mac_Portable_x86_64.dmg + 了 txt 后缀","image":"https://pub-45173be2cbbc428081b442b7a70d25a0.r2.dev/tt-moto-coder-pics/production/images/item-e260c57775b7fd789458606a49e66e7c.png","date_published":"2025-06-17T09:41:04.247Z","_microfeed":{"is_audio":false,"is_document":true,"is_external_url":false,"is_video":false,"is_image":false,"web_url":"https://tt-moto-coder-pics.pages.dev/i/什么是好的技术文档-z25d60q0Wrs/","json_url":"https://tt-moto-coder-pics.pages.dev/i/z25d60q0Wrs/json/","rss_url":"https://tt-moto-coder-pics.pages.dev/i/z25d60q0Wrs/rss/","guid":"z25d60q0Wrs","status":"published","itunes:episodeType":"full","date_published_short":"Tue Jun 17 2025","date_published_ms":1750153264247}}],"_microfeed":{"microfeed_version":"0.1.5","base_url":"https://tt-moto-coder-pics.pages.dev","categories":[{"name":"Technology"},{"name":"Science","categories":[{"name":"Life Sciences"}]}],"subscribe_methods":[{"name":"RSS","type":"rss","url":"https://tt-moto-coder-pics.pages.dev/rss/","image":"https://tt-moto-coder-pics.pages.dev/assets/brands/subscribe/rss.png","enabled":true,"editable":false,"id":"cxE9Dn2GIlD"},{"name":"JSON","type":"json","url":"https://tt-moto-coder-pics.pages.dev/json/","image":"https://tt-moto-coder-pics.pages.dev/assets/brands/subscribe/json.png","enabled":true,"editable":false,"id":"khNgkL6_6t8"}],"description_text":"\n\n\n * Coder/Developer/MotoRider\n * Rust/Golang/Java/C/Python/Android\n * Game Player\n * Blockchain Believe\n * 《请回答1988》,Naruto, 武林外传 粉丝\n * 座驾：巡航复古摩托车TR300\n * Previous Airbnb host","itunes:title":"骑摩托写代码的天天","copyright":"©2026","itunes:type":"serial","itunes:email":"3060326200@qq.com","items_sort_order":"newest_first"}}