搜索

[26409] 2021-04-05_程序员最烦写文档

文档创建者：s7ckTeam
浏览次数：1
最后更新：2025-01-19
2021-04-05_程序员最烦写文档 程 序 员 最 烦 写 文 档 图 灵 君   L i n u x 学 习   2 0 2 1 - 0 4 - 0 5 查 看 文 章 尾 部 参 与 赠 书 活 动 查 看 文 章 尾 部 参 与 赠 书 活 动 文 档 是 程 序 开 发 过 程 中 的 蓖 麻 油 ： 主 管 们 认 为 它 会 对 程 序 员 有 益 ， 而 程 序 员 却 讨 厌 它 ！ — — G e r a l d   W e i n b e r g ， 《 程 序 开 发 心 理 学 》 据 说 程 序 员 最 烦 写 文 档 ， 第 二 烦 其 他 人 没 写 文 档 。 当 你 听 到 文 档 文 档 这 个 词 会 想 到 什 么 ？ 它 很 无 聊 。 要 写 很 多 字 。 意 味 着 你 要 试 着 使 用   M i c r o s o f t   W o r d ， 还 不 能 忘 了 在 哪 里 插 入 图 片 。 作 为 开 发 人 员 ， 我 喜 欢 那 些 展 现 动 作 和 行 为 的 动 态 可 执 行 文 件 。 对 我 而 言 ， 文 档 是 静 止 的 ， 它 就 像 一 株 枯 草 ， 了 无 生 趣 。 本 来 以 为 它 能 帮 上 忙 ， 结 果 总 是 耽 误 事 儿 . . . . . . 写 文 档 很 无 聊 ， 我 宁 愿 写 代 码 也 不 愿 意 编 写 文 档 ！ 我 还 是 写 代 码 去 吧 我 还 是 写 代 码 去 吧 . . . . . . 编 写 和 维 护 文 档 需 要 大 量 时 间 。 文 档 很 快 就 会 过 时 ， 通 常 不 完 整 ， 编 写 文 档 和 阅 读 文 档 的 过 程 令 人 沮 丧 . . . . . . 是 的 ， 程 序 员 眼 里 的 文 档 就 是 这 样 ， 而 且 大 家 还 能 “ 如 数 家 珍 ” 地 列 出 文 档 的 十 大 缺 陷 十 大 缺 陷 。 传 统 文 档 的 缺 陷 传 统 文 档 的 缺 陷 就 像 劣 质 酒 的 香 味 会 快 速 消 失 一 样 ， 纸 质 文 档 的 内 容 也 会 迅 速 失 效 ， 令 你 头 痛 不 已 。 — — @ g o j k o a d z i c
传 统 文 档 存 在 许 多 缺 陷 和 几 种 常 见 的 反 模 式 。 几 乎 每 个 程 序 员 的 项 目 中 都 有 以 下 列 出 的 这 样 或 者 那 样 的 问 题 。 1 .   自 扫 门 前 雪 自 扫 门 前 雪 即 便 是 在 声 称 “ 敏 捷 ” 的 软 件 开 发 项 目 中 ， 决 定 构 建 内 容 、 编 码 、 测 试 和 准 备 文 档 这 几 项 工 作 之 间 也 常 常 是 相 互 独 立 的 。 自 扫 门 前 雪 自 扫 门 前 雪 活 动 之 间 相 互 独 立 会 浪 费 大 量 时 间 并 错 失 一 些 好 机 会 。 基 本 上 ， 所 有 的 活 动 都 会 用 到 相 同 的 知 识 ， 只 是 以 不 同 的 形 式 和 工 件 来 使 用 ， 并 且 可 能 伴 有 一 定 程 度 的 重 复 。 另 外 ， 在 流 程 中 ， 这 些 “ 相 同 ” 的 知 识 可 能 会 演 进 发 展 ， 从 而 导 致 不 同 活 动 中 的 知 识 内 容 不 一 致 。 2 .   为 文 档 再 写 一 份 文 档 为 文 档 再 写 一 份 文 档 需 要 编 写 文 档 时 ， 团 队 成 员 会 选 择 一 些 已 完 成 工 作 的 知 识 要 素 ， 然 后 手 动 将 它 们 转 化 成 适 合 目 标 受 众 的 格 式 。 基 本 上 ， 这 是 一 个 为 代 码 里 已 经 写 好 的 文 档 再 写 一 份 文 档 的 过 程 ， 就 像 古 登 堡 发 明 印 刷 机 之 前 的 抄 写 员 一 样 。 为 代 码 里 已 经 写 好 的 文 档 再 写 一 份 文 档 为 代 码 里 已 经 写 好 的 文 档 再 写 一 份 文 档 3 .   文 档 很 快 就 会 过 时 文 档 很 快 就 会 过 时 以 上 描 述 的 “ 抄 写 ” 过 程 导 致 了 知 识 的 重 复 ： 最 终 ， 你 获 得 了 反 映 真 实 情 况 的 原 始 知 识 来 源 （ 通 常 是 代 码 ） 和 一 堆 以 各 种 形 式 复 制 成 的 知 识 副 本 。 不 幸 的 是 ， 当 一 个 工 件 （ 例 如 代 码 ） 发 生 变 化 时 ， 你 很 难 记 得 要 更 新 其 他 文 档 。 于 是 ， 文 档 内 容 很 快 就 过 时 了 ， 留 给 你 的 是 一 份 无 法 信 任 的 不 完 整 文 档 。 这 样 的 文 档 有 什 么 用 呢 ？
4 .   无 聊 的 时 间 陷 阱 无 聊 的 时 间 陷 阱 管 理 层 想 为 用 户 提 供 文 档 ， 还 想 用 文 档 来 解 决 团 队 中 人 员 流 动 引 发 的 问 题 。 然 而 ， 开 发 人 员 讨 厌 编 写 文 档 。 与 写 代 码 或 使 任 务 自 动 化 相 比 ， 写 文 档 一 点 意 思 也 没 有 。 对 于 开 发 人 员 来 说 ， 他 们 不 太 有 兴 趣 编 写 一 些 会 迅 速 过 时 且 无 法 执 行 的 无 效 文 本 。 当 开 发 人 员 需 要 写 文 档 时 ， 他 们 宁 愿 去 处 理 真 正 在 工 作 的 软 件 。 矛 盾 的 是 ， 当 他 们 想 复 用 第 三 方 软 件 矛 盾 的 是 ， 当 他 们 想 复 用 第 三 方 软 件 时 ， 一 般 希 望 能 有 更 多 有 用 的 文 档 。 时 ， 一 般 希 望 能 有 更 多 有 用 的 文 档 。 技 术 文 档 工 程 师 喜 欢 写 文 档 ， 而 且 以 此 为 生 。 但 是 ， 他 们 通 常 需 要 开 发 人 员 的 协 助 才 能 获 得 编 写 文 档 所 需 的 技 术 知 识 ， 而 且 经 常 做 的 仍 是 “ 手 抄 ” 知 识 。 这 个 过 程 令 人 沮 丧 ， 也 浪 费 了 大 量 宝 贵 的 时 间 。 掉 进 编 写 文 档 的 掉 进 编 写 文 档 的 “ 时 间 陷 阱 时 间 陷 阱 ” 5 .   想 到 什 么 写 什 么 想 到 什 么 写 什 么 因 为 编 写 文 档 不 是 一 件 有 趣 的 事 ， 而 且 我 们 只 是 因 为 必 须 要 有 文 档 才 会 这 么 做 ， 所 以 编 写 文 档 时 一 般 比 较 随 意 ， 不 会 考 虑 太 多 。 结 果 是 作 者 在 编 写 文 档 时 就 做 了 “ 脑 转 储 ” ， 即 想 到 什 么 就 写 什 么 。 问 题 在 于 ， 这 种 随 机 的 脑 转 储 对 任 何 人 都 无 益 。 想 到 什 么 写 什 么 ， 文 档 不 一 定 有 用 想 到 什 么 写 什 么 ， 文 档 不 一 定 有 用 6 .   优 美 的 图 表 优 美 的 图 表 对 于 那 些 喜 欢 使 用 C A S E （ C o m p u t e r - A s s i s t e d   S o f t w a r e   E n g i n e e r i n g ， 计 算 机 辅 助 软 件 工 程 ） 工 具 的 人 来 说 ， 这 种 反 模 式 很 常 见 。 这 些 工 具 并 不 是 为 制 作 草 图 设 计 的 。 相 反 ， 它 们 鼓 励 使 用 各 种 布 局 和 根 据 建 模 参 考 的 验 证 来 创 建 优 美 的 大 型 图 表 。 整 个 过 程 需 要 很 长 时 间 。 即 使 这 些 工 具 能 神 奇 地 自 动 完 成 布 局 ， 创 建 一 个 简 单 的 图 表 仍 然 需 要 很 长 时 间 。
7 .   迷 恋 符 号 迷 恋 符 号 我 们 发 现   U M L   符 号 现 在 越 来 越 不 受 欢 迎 了 。 U M L   在   1 9 9 7   年 被 采 用 为 标 准 ， 并 在 之 后 的 十 年 里 成 为 所 有 软 件 的 通 用 符 号 ， 尽 管 它 并 不 适 用 于 所 有 情 况 。 从 那 时 起 ， 再 也 没 有 其 他 符 号 被 广 泛 地 使 用 ， 而 且 即 使 不 太 合 适 ， 世 界 各 地 的 团 队 仍 会 用 一 些 U M L 符 号 来 记 录 内 容 。 当 你 只 知 道   U M L   时 ， 每 一 个 图 表 看 起 来 都 像 是 它 的 标 准 图 集 之 一 。 8 .   不 用 符 号 不 用 符 号 实 际 上 ， 与 迷 恋 符 号 完 全 相 反 的 另 一 个 极 端 已 经 相 当 普 遍 了 。 许 多 人 完 全 无 视 U M L ， 使 用 一 些 没 人 能 理 解 的 自 定 义 符 号 绘 制 图 表 ， 并 将 诸 如 构 建 依 赖 项 、 数 据 流 和 部 署 之 类 的 随 机 问 题 混 为 一 谈 。 9 .   信 息 墓 地 信 息 墓 地 企 业 知 识 管 理 解 决 方 案 是 知 识 消 亡 的 地 方 。 看 看 这 些 ： 企 业   w i k i S h a r e P o i n t 大 型   M i c r o s o f t   O f f i c e   文 档 共 享 文 件 夹 搜 索 功 能 很 差 的 工 单 系 统 和   w i k i 这 些 文 档 编 写 方 法 通 常 会 失 败 ， 要 么 是 因 为 通 过 它 们 很 难 找 到 正 确 的 信 息 ， 要 么 是 因 为 将 信 息 保 持 最 新 状 态 需 要 大 量 工 作 ， 或 者 两 者 皆 有 。 这 些 方 法 促 进 了 只 写 文 档 （ w r i t e - o n l y   d o c u m e n t a t i o n ） 或 只 写 一 次 文 档 （ w r i t e - o n c e d o c u m e n t a t i o n ） 的 形 式 。 在 最 近 的 一 次   T w i t t e r   交 流 中 ， 著 名 软 件 开 发 商   T i m   O t t i n g e r （ @ t o t t i n g e ） 问 了 这 样 一 个 问 题 。 产 品 类 别 ： “ 文 档 墓 地 ” — — 所 有 文 档 管 理 、 w i k i 、 S h a r e P o i n t   和 团 队 空 间 是 否 注 定 失 败 ？ J a m e s   R .   H o l m e s （ @ J a m e s _ R _ H o l m e s ） 回 复 如 下 。 我 们 的 标 准 笑 话 是 这 样 的 ： 说 “ 它 在 内 网 上 ” 会 引 发 “ 你 刚 刚 是 让 我 自 己 去 _ _ _ _ 吗 ？ ” 的 回 应 。   （ 注 意 ： 因 为 原 话 用 了 粗 俗 的 语 句 ， 所 以 做 了 编 辑 ， 你 懂 的 。 ） 1 0 .   误 导 性 的 帮 助 误 导 性 的 帮 助 只 要 文 档 不 能 严 格 保 持 最 新 ， 就 会 产 生 一 定 的 误 导 性 。 虽 然 文 档 看 起 来 有 用 ， 但 事 实 上 是 错 误 的 。 因 此 ， 这 些 文 档 可 能 读 起 来 有 意 思 ， 但 是 辨 别 哪 些 内 容 仍 然 正 确 以 及 哪 些 内 容 已 经 不 再 正 确 会 造 成 额 外 的 认 知 负 担 。
当 文 档 无 法 正 确 指 导 用 户 时 ， 它 就 是 有 害 的 当 文 档 无 法 正 确 指 导 用 户 时 ， 它 就 是 有 害 的 编 写 高 质 量 的 文 档 需 要 很 多 时 间 ， 而 维 护 它 往 往 需 要 更 长 时 间 更 长 时 间 。 如 果 一 个 人 时 间 紧 迫 ， 他 就 会 经 常 略 过 文 档 任 务 ， 或 者 快 速 、 粗 糙 地 完 成 文 档 。 毕 竟 ， 咱 们 总 有 “ 比 写 文 档 更 重 要 的 事 ” 。 然 而 ， 真 实 的 情 况 是 什 么 ？ 开 发 人 员 经 常 因 为 缺 失 有 效 文 档 而 “ 抓 狂 ” ， 软 件 经 常 因 为 缺 失 有 效 文 档 而 为 开 发 人 员 所 “ 诟 病 ” 。 既 然 ， 文 档 相 关 的 问 题 如 此 严 重 ， 是 时 候 了 解 一 下 文 档 文 档   2 . 0   了 。 活 文 档 活 文 档 自   2 0   世 纪   9 0   年 代 末 以 来 ， 诸 如 整 洁 的 代 码 、 测 试 驱 动 开 发 （ T D D ） 、 行 为 驱 动 开 发 （ B D D ） 、 领 域 驱 动 设 计 （ D D D ） 和 持 续 交 付 之 类 的 实 践 越 来 越 流 行 。 这 些 实 践 改 变 了 我 们 关 于 软 件 交 付 的 思 考 方 式 。 现 在 ， 我 们 终 于 可 以 期 待 有 这 样 一 种 文 档 编 写 方 法 ： 它 实 用 ， 能 使 文 档 内 容 永 远 保 持 最 新 成 本 低 ， 并 能 让 编 写 文 档 变 得 有 趣 这 就 是 活 文 档 的 核 心 理 念 ， 它 要 解 决 传 统 文 档 存 在 的 问 题 。 具 体 是 怎 么 解 决 的 呢 ？ 西 里 尔 · 马 特 雷 尔 （ C y r i l l e   M a r t r a i r e ） 是 个 创 业 公 司 的   C T O ， 软 件 设 计 专 家 ， 曾 领 导 过 多 个 重 大 项 目 ， 在 处 理 大 型 遗 留 系 统 方 面 经 验 丰 富 。 2 0 1 3   年 ， 在   Ö r e d e v   技 术 会 议 上 首 次 系 统 提 到 活 文 档 时 ， 引 发 了 与 会 人 员 的 强 烈 兴 趣 。 此 后   5   年 多 的 时 间 ， 西 老 师 专 注 于 系 统 化 他 这 套 理 念 ， 以 及 实 践 更 多 的 方 法 。 2 0 1 9   年   5   月 ， 西 老 师 出 版 了 一 本 书 ， 名 为   L i v i n g   D o c u m e n t a t i o n :   C o n t i n u o u s   K n o w l e d g e   S h a r i n g   b y   D e s i g n ， 图 灵 将 这 本 书 引 入 ， 就 是 今 天 为 大 家 介 绍 的 这 本 ： 《 活 文 档 ： 与 代 码 共 同 演 进 》 。
A m a z o n   读 者 给 这 本 书 打 出 了   4 . 4   星 的 好 评 ， 我 们 在 发 布 纸 质 书 之 前 ， 邀 请 一 些 专 家 和 普 通 读 者 试 读 了 部 分 章 节 ， 大 家 表 示 文 档 相 关 问 题 早 已 令 人 “ 头 秃 ” ， 这 本 书 可 谓 “ 及 时 雨 ” 。 通 过 以 下 目 录 ， 诸 位 可 以 深 入 看 看 作 者 是 怎 么 通 过 活 文 档 逐 步 解 决 传 统 文 档 的 痛 点 的 。 目 录 目 录 |   左 右 滑 左 右 滑 动 动
可 双 击 图 片 放 大 查 看 可 双 击 图 片 放 大 查 看 目 录 有 接 近 目 录 有 接 近   7   页 ， 相 当 详 尽 页 ， 相 当 详 尽 也 可 以 点 击 「 阅 读 原 文 」 前 往 图 灵 社 区 试 读 更 多 内 容 这 本 书 的 特 色 是 什 么 ？ 看 图 ， 简 单 概 括 。 脉 络 、 逻 辑 、 文 风 都 很 棒 ！


业 内 专 家 张 逸 、 朱 少 民 、 张 银 奎 和 刘 冉 四 位 老 师 提 前 审 阅 了 本 书 ， 并 给 出 了 阅 读 引 荐 。 张 逸 老 师 还 专 门 写 了 推 荐 文 章 ， 详 细 阐 述 了 他 对 本 书 的 评 价 及 如 何 在 工 作 中 实 践 相 关 的 方 法 。
回复

举报

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

使用Markdown编辑器编辑 使用富文本编辑器编辑

Archiver| 手机版| 小黑屋|
Powered by Discuz! X3.4 Copyright © 2001-2020, Tencent Cloud. 商业源码建议获取授权，如侵犯您的权益，请联系客服处理