1. 明明都叫“01_概述”为什么有人写成了废话元旦前整理一个跨部门项目的文档我发现一个特别普遍的现象文档目录里排第一的永远是“01_概述”可点进去之后要么是两三句含糊其辞的套话要么是从需求文档里复制过来的大段列表。几乎没有一个人愿意承认自己其实不太会写概述。我想先说一句可能会得罪同行的话概述不是拿来凑字数的它是整个项目文档的导航图。你搭得好后面所有章节自然有人看得下去你搭得稀烂后面内容再专业也会被埋没。这篇博客我就想认真聊聊项目文档里那章“01_概述”到底该怎么写以及我在不同项目里反复验证过的一套框架和踩坑经验。1.1 概述不是摘要也不是公司宣传稿“概述”这个词被用滥了。很多人把它当成“摘要”做法是把后面章节各抄一段拼在一起再润色一下就算完成。还有人把它当“致辞”开头放一段背景意义中间吹几句愿景结尾写一句“希望通过本项目的实施全面提升公司信息化水平”。这两种都跑偏了。概述的职责只有一条让一个完全不了解上下文的新读者在五到十分钟之内判断出——这个项目要解决什么问题、为谁解决、解决到什么程度、不解决什么、以及后续从哪里找到详细说明。它是一座桥不是一面广告牌。如果读者看完概述后脑子里依然一团模糊那不管它写得多么流畅、多么充满使命感都算失败。1.2 那些“写了等于没写”的概述长什么样如果把我见过的失败案例归类基本逃不出下面几种内容全是一堆正确的废话。“本项目致力于提升企业运营效率实现管理精细化、流程标准化……”这类句子放到任何一个项目身上都成立所以等于没有。篇幅只有一段且全用形容词。“该项目技术先进、架构合理、操作方便、功能全面。”四个词里有三个是主观感受读者无法据此做任何决策。把背景写成行业论文。开篇三页讲述行业痛点、市场趋势、国内外现状就是不说自己的系统要做什么。目标过度承诺。项目还没立项概述里已经写“全面提升”“彻底解决”“显著改善”却没有一个可量化的判据。这些文档最终的命运都一样团队变动之后没人会回去读它因为读了也得不到有用信息。我曾经在一个项目里做过一个小试验让两位新入职的同事各花十分钟读概述然后请他们回答“这个项目最重要的三个成功标准是什么”。结果两个人给出的答案完全不同。那一刻我就明白概述写不清楚后面所有协作都要靠口口相传而口口相传一定会失真。1.3 概述会写废卡在没想清楚“给谁看”我反复追问过项目成员一个问题“概述是写给谁看的”答案经常是“给领导看的”“给客户看的”“给评审专家看的”。一旦出现这种回答概述就注定会写成汇报材料。一个可靠的判断标准是你写概述的时候脑子里必须有一个具体的人比如三周后加入项目的后端工程师小王或者两个月后接手验收的运营负责人李姐。他是第一次接触项目手头只有这一份文档他能不能靠“01_概述”建立起正确的心智模型如果能说明你写到位了。如果不能哪怕领导觉得“文笔不错”这章也依然是废品。概述本质上是项目治理的一部分它不是为了展示文采而是为了统一认知。2. 拆解概述的骨架背景、目标、范围、术语和风险既然概述是给新读者的导航图那它就要有稳定的骨架。我在实践里总结出五个必备模块背景、目标、范围、术语、风险。缺少任何一个读者都会在后续章节里迷路。2.1 背景部分只写“为什么现在要做”背景不需要写远古历史也不需要畅想遥远未来。它只需回答为什么是现在发生了什么变化导致我们必须启动这个项目举个例子如果是做企业内部培训平台你不需要写“在线教育行业发展迅速”而要写这样的场景“公司内部培训仍靠手工登记和邮件报名过去半年出现多次课程容量超售和学分统计错误业务部门已连续两个季度提出投诉。”这个背景把时间、现象、后果全部点出来了。读者一看就知道项目的出发点在哪。反过来如果背景里全是“与时俱进”“顺应趋势”那它无法帮助读者理解任何决策。背景部分我建议控制在100字左右超过150字就基本可以判定为写成了行业综述。2.2 目标部分必须给出可验证的判据目标不能是口号。概述里的目标应该能在项目结束时被客观检查。比如将课程排期调整的平均耗时从3个工作日压缩到1个工作日内。将新员工培训报名操作步骤从6步压缩到3步。实现学分自动累计使每月手工核对时间从2人天降到0.2人天。这几个目标都包含度量方式、基线值和预期值。而“提高排课效率”就无法验证因为“效率”没有单位。我见过太多项目验收时扯皮根源就在于目标章节里只有一堆高瞻远瞩的形容词没有可以按下计算器的数字。这一条我会在第三章专门展开。2.3 范围、术语和风险三块容易被低估的拼图范围是概述里的“护栏”它告诉读者哪些内容属于本项目哪些不属于。没有护栏读者很容易按自己的想象脑补。术语则是一种“协商工具”项目里常有各种缩写比如 LIS、BI、SSO、API新读者看到时如果没人解释后面段落就全成了天书。风险更好理解它写的是项目启动时就知道的不确定因素比如“培训数据从老系统迁移可能存在字段缺失”“第三方审批接口的响应时限未书面确认”。把风险放进概述不是为了吓人而是为了提醒读者看后面相应章节时带着问题。这三块平时不需要太长但必须真实。尤其是术语部分别只放高大上的学术名词要把内部常用黑话也列进去。比如团队内部常说“打平”意思是“数据拉平对齐”如果新人不了解理解就会产生偏差。3. 目标不是写出来而是定出来从“要什么”到“不要什么”3.1 目标书写的“动词陷阱”我刚带项目时最喜欢玩一个游戏把目标句子中的动词全部圈出来然后数一数有多少是无监督动词。什么叫无监督动词就是“优化”“提升”“加强”“完善”“促进”它们后面必须跟一个可观测对象才能落地。如果写成“优化培训管理流程”你无法验收如果写成“将培训报名操作步骤从6步压缩到3步”任何人都能判断做没做到。所以我给团队立了一条规矩目标句里不允许出现无监督动词除非在同一句话里给出了测量方法。这句话值得打印出来贴在工位上。你可以看下面这个对比表格不合格目标合格目标提升培训管理效率将培训报名平均耗时从5分钟降到2分钟加强数据准确性将学分录入错误率从5%降到0.5%以下改善用户体验将关键操作路径的页面响应时间从3秒降到1秒以内完善报表功能新增并上线12张标准经营分析报表合格目标都自带“仪表盘”。没有仪表盘的目标写得再漂亮也只是愿望清单。3.2 非目标把“No”明确写出来很多项目的范围蔓延根源不在范围章节而在“非目标”没写。不做什么其实比做什么更能定义项目的边界。举个例子目标非目标理由支持课程在线报名与学分自动累计不做复杂排课系统排课由线下运营团队维护本期只做打通提供管理员端数据导出不做可视化大屏大屏需求未冻结放到二期评估兼容主流移动端浏览器不做原生App公司当前策略是H5优先原生App无独立团队支撑这张表格比十段文字都有用。新成员看到后不会再来问你“要不要支持XX”他会先对照这份清单。如果你的概述里没有“非目标”这一节那说明你还没真正想清楚项目的边界后面被临时加需求的概率会非常高。3.3 一个可迁移的目标定义流程我每次写概述目标前会强制自己走四步列出项目干系人最近抱怨最多的三个痛点从业务方原话里提取关键词。给每个痛点配上可以量化的指标。指标可以是时间、次数、金额、成功率尽量别用“满意度”这种不容易设计的词。把“现状值”和“期望值”同时写出来。例如“现状每次培训反馈统计需3人天期望自动生成报表后降至0.5人天”。删掉那些“锦上添花”的目标。如果这个目标无法在六个月内落地就别写进概述宁可放到“后续规划”。这个过程看起来简单但关键在于“从业务原话提取”而不是从技术方案反推。目标应该来自问题不是来自功能。我见过有人从系统架构图反推出二十多条目标每条都是“支持XX模块、实现XX能力”那叫功能清单不叫目标。4. 范围边界是概述里最容易翻车的地方4.1 范围写得太粗等于没写我看到过这样的范围描述“本项目包含培训管理、课程管理、学员管理、数据分析。”这看起来列了四块但“数据分析”具体指什么是统计报表还是数据挖掘范围粒度太粗会等同于没说。读者会按自己的经验去猜测边界十个人能猜出十种版本。更严重的是范围太粗还给后期争论留下了空间。业务方可以指着“数据分析”四个字说“我要求做用户行为分析你没做所以项目不完整。”而项目组可以辩解说“我们理解的数据分析就是报表。”这种分歧如果放在概述阶段只需要多写一行“数据分析只包含固定报表不包含用户行为分析探索”就能避免。4.2 范围写得太细文档会迅速过期反过来也有团队把范围写到“按钮颜色”“提示文案措辞”。短期内固然清晰但系统界面一调整概述就失效最后变成一堆没人维护的废料。概述里的范围应该停在“模块级”或“能力级”描述这个模块负责什么、依赖什么而不是描述界面元素。例如培训管理负责培训项目的创建、发布、报名、签到、学时记录依赖组织架构数据来自主数据系统。这个粒度就比较合适。它告诉读者模块的大职责和依赖关系但不会因为某个按钮改了颜色就需要更新。把控粒度是个手感活我的经验是如果你写范围时犹豫“这条是不是太细了”那就把它从概述里删掉放到对应的章节里去。4.3 用“包含、不包含、边界”三份清单锁住我自己的习惯是在概述里用三个短清单描述范围包含列出本项目明确交付的能力模块。不包含列出经常被误认为属于本项目的功能。边界说明和周边系统的关系比如“本系统不存储组织架构只通过接口读取当组织架构更新时实时同步延迟不超过30分钟。”有了这三个清单评审会上的大量争论都能前移到文档阶段解决。因为“不包含”清单的存在干系人看到自己关心但没有被纳入的功能时会提前提出异议这比开发到一半再改要好得多。我有一次写“不做原生App”业务负责人当场表示反对后经过讨论确认web端已经满足场景才把这个分歧固化下来。如果我没写“不包含”这个问题可能要拖到测试阶段才爆发。5. 概述也要版本控制文档活不活得下去全看这里5.1 概述的维护人要唯一大多数项目文档死了不是因为没人读而是因为没人改。概述更是重灾区。一份概述写完之后如果项目发生变化没人负责更新六个月后再看它描述的系统已经和现实完全对不上了。我建议在概述开头标注“维护人”且只能有一个人。这个人通常由项目经理或技术负责人兼任。维护人的职责不是每次变更都去改正文而是判断这个变更是否会动摇概述中的任何一句陈述——比如目标改了、范围边界改了、核心术语含义改了。只要有一点变化就必须立刻更新概述并记录日期。如果只是某个Button进不了微调那完全不用管。这个判断能力比实际动手改文档更重要。5.2 变更行为要回写到版本历史很多人觉得版本历史只是形式主义但它其实是概述“保真”的关键。没有版本历史读者不知道当前段落是何时写的也不知道为什么要改。一张简单的表格就能解决版本日期修改人修改说明v0.12024-02-01张三完成初稿培训模块范围待业务确认v0.22024-02-20李四增加非目标“不做可视化大屏”补充术语表v0.32024-03-05张三目标指标调整报表耗时从0.5人天改为0.3人天这张表支撑了文档的可追溯性。新成员问“为什么当初不做大屏”不看聊天记录只看版本历史就能明白。我建议把“和概述对齐”纳入项目例会比如周会第一项议程固定为“概述是否需要更新”。不需要时十秒跳过需要时当场合入。这个动作看似琐碎执行起来效果极其明显。5.3 概述不更新会带来真实返工讲一个我踩过的坑。曾经有个项目第一期说好不做“权限审批流”所有审批走邮件。结果中途一个关键客户提出要求团队临时加了审批流并成功上线。功能做完了但概述里的范围依然写着“不做权限审批流”。半年后二期启动新来的产品经理基于旧概述做规划又投入三个人评估审批流的可行性相当于把已经做过的事重新设计了一遍。发现真相的那一刻整个团队都沉默了。这就是概述不更新的代价你以为文档只是旧实际上它会直接导致后续决策浪费真金白银。所以我现在对概述的版本历史特别敏感。它不是用来向上汇报的装饰而是项目记忆的一部分。6. 一个可以直接套用的概述模板附注释与避坑清单6.1 模板的核心结构下面是我目前在项目文档中实际使用的概述模板可以直接复制过去改成自己项目的。注意每个部分后面的“写法提示”才是重点。# 01 概述 ## 1.1 文档信息 - 维护人[姓名] - 最近更新日期[日期] - 适用读者[项目经理 / 开发 / 测试 / 业务方 / 新入职成员] ## 1.2 背景 [为什么是现在做这个项目出现了哪些具体问题带来什么业务影响用3~5句话描述不要泛化。] ## 1.3 目标 - G1[可验证目标1含基线值和期望值] - G2[可验证目标2含基线值和期望值] - G3[可验证目标3含基线值和期望值] ## 1.4 非目标 - N1[明确不做的功能或边界] - N2[明确不做的功能或边界] ## 1.5 范围 - 包含[模块/能力清单按系统业务模块组织] - 不包含[易被误认为在本项目内的功能] - 边界[与外部系统的依赖关系、数据流向、时效约束] ## 1.6 术语表 | 术语 | 解释 | |---|---| | XX | 指什么注意和相近概念的区别 | ## 1.7 风险与开放问题 - R1[已知风险] - R2[待确认问题]你看整个模板里最长的地方其实是“术语表”和“范围”。背景、目标、非目标都要求短而准。概述不是用来提供完整细节的它是用来让读者建立全局地图的。细节必须放到后面的章节。6.2 各部分篇幅建议背景控制在100字左右。如果超过150字就要怀疑是不是在写行业报告。目标与非目标目标3~5条非目标2~4条每条不超过30字。范围包含、不包含、边界各5~10项每项不超过一行。术语表只收新读者可能会困惑的不要收“系统登录”这种常识词。风险列已知事实不要列臆测。这些数字不是硬性规定但当你发现“概述”章节比后面所有章节都长时大概率是写偏了。概述应该短到新读者愿意读完又长到能回答核心问题。我见过一个极端例子某个文档“01_概述”写了四十页几乎把验收测试用例都放进去了结果根本没人读。文档的可用性和完整性需要平衡而概述明显应该偏向可用性。6.3 写完之后的自检清单我一般在提交文档前会再过一遍这份自检清单它帮我抓出过不少问题读完概述能不能说出项目“不做什么”目标里所有动词是否都能被客观测量如果删掉背景段落目标和范围是否仍然成立术语表里的缩写是否至少在当前文档的首次出现处有对应解释是否指定了唯一的维护人最近一次项目变更后概述里是否有过期的描述如果这六条里有一条不满足我就会改完再提交。虽然每次都多花十几分钟但它能省掉后面无数次的解释和纠偏。特别是最后一条我吃过太多亏了。有时候只是因为改了某个接口字段的名称却忘了同步到概述术语表导致新人在对接时拿旧字段名去查代码白白浪费了两个小时。这算是一个从实践中沉淀下来的概述写作框架。我最初也是被人问“你文档里写的目标到底怎么验收”时被迫开始一点点修正后来才形成现在这版结构。项目类型会变但这几个模块和原则几乎没有变过。如果你现在正要去写“01_概述”不妨先别急着打开空白文档花十分钟想清楚读者是谁再把这个模板填进去效果会好很多。
1. 明明都叫“01_概述”为什么有人写成了废话元旦前整理一个跨部门项目的文档我发现一个特别普遍的现象文档目录里排第一的永远是“01_概述”可点进去之后要么是两三句含糊其辞的套话要么是从需求文档里复制过来的大段列表。几乎没有一个人愿意承认自己其实不太会写概述。我想先说一句可能会得罪同行的话概述不是拿来凑字数的它是整个项目文档的导航图。你搭得好后面所有章节自然有人看得下去你搭得稀烂后面内容再专业也会被埋没。这篇博客我就想认真聊聊项目文档里那章“01_概述”到底该怎么写以及我在不同项目里反复验证过的一套框架和踩坑经验。1.1 概述不是摘要也不是公司宣传稿“概述”这个词被用滥了。很多人把它当成“摘要”做法是把后面章节各抄一段拼在一起再润色一下就算完成。还有人把它当“致辞”开头放一段背景意义中间吹几句愿景结尾写一句“希望通过本项目的实施全面提升公司信息化水平”。这两种都跑偏了。概述的职责只有一条让一个完全不了解上下文的新读者在五到十分钟之内判断出——这个项目要解决什么问题、为谁解决、解决到什么程度、不解决什么、以及后续从哪里找到详细说明。它是一座桥不是一面广告牌。如果读者看完概述后脑子里依然一团模糊那不管它写得多么流畅、多么充满使命感都算失败。1.2 那些“写了等于没写”的概述长什么样如果把我见过的失败案例归类基本逃不出下面几种内容全是一堆正确的废话。“本项目致力于提升企业运营效率实现管理精细化、流程标准化……”这类句子放到任何一个项目身上都成立所以等于没有。篇幅只有一段且全用形容词。“该项目技术先进、架构合理、操作方便、功能全面。”四个词里有三个是主观感受读者无法据此做任何决策。把背景写成行业论文。开篇三页讲述行业痛点、市场趋势、国内外现状就是不说自己的系统要做什么。目标过度承诺。项目还没立项概述里已经写“全面提升”“彻底解决”“显著改善”却没有一个可量化的判据。这些文档最终的命运都一样团队变动之后没人会回去读它因为读了也得不到有用信息。我曾经在一个项目里做过一个小试验让两位新入职的同事各花十分钟读概述然后请他们回答“这个项目最重要的三个成功标准是什么”。结果两个人给出的答案完全不同。那一刻我就明白概述写不清楚后面所有协作都要靠口口相传而口口相传一定会失真。1.3 概述会写废卡在没想清楚“给谁看”我反复追问过项目成员一个问题“概述是写给谁看的”答案经常是“给领导看的”“给客户看的”“给评审专家看的”。一旦出现这种回答概述就注定会写成汇报材料。一个可靠的判断标准是你写概述的时候脑子里必须有一个具体的人比如三周后加入项目的后端工程师小王或者两个月后接手验收的运营负责人李姐。他是第一次接触项目手头只有这一份文档他能不能靠“01_概述”建立起正确的心智模型如果能说明你写到位了。如果不能哪怕领导觉得“文笔不错”这章也依然是废品。概述本质上是项目治理的一部分它不是为了展示文采而是为了统一认知。2. 拆解概述的骨架背景、目标、范围、术语和风险既然概述是给新读者的导航图那它就要有稳定的骨架。我在实践里总结出五个必备模块背景、目标、范围、术语、风险。缺少任何一个读者都会在后续章节里迷路。2.1 背景部分只写“为什么现在要做”背景不需要写远古历史也不需要畅想遥远未来。它只需回答为什么是现在发生了什么变化导致我们必须启动这个项目举个例子如果是做企业内部培训平台你不需要写“在线教育行业发展迅速”而要写这样的场景“公司内部培训仍靠手工登记和邮件报名过去半年出现多次课程容量超售和学分统计错误业务部门已连续两个季度提出投诉。”这个背景把时间、现象、后果全部点出来了。读者一看就知道项目的出发点在哪。反过来如果背景里全是“与时俱进”“顺应趋势”那它无法帮助读者理解任何决策。背景部分我建议控制在100字左右超过150字就基本可以判定为写成了行业综述。2.2 目标部分必须给出可验证的判据目标不能是口号。概述里的目标应该能在项目结束时被客观检查。比如将课程排期调整的平均耗时从3个工作日压缩到1个工作日内。将新员工培训报名操作步骤从6步压缩到3步。实现学分自动累计使每月手工核对时间从2人天降到0.2人天。这几个目标都包含度量方式、基线值和预期值。而“提高排课效率”就无法验证因为“效率”没有单位。我见过太多项目验收时扯皮根源就在于目标章节里只有一堆高瞻远瞩的形容词没有可以按下计算器的数字。这一条我会在第三章专门展开。2.3 范围、术语和风险三块容易被低估的拼图范围是概述里的“护栏”它告诉读者哪些内容属于本项目哪些不属于。没有护栏读者很容易按自己的想象脑补。术语则是一种“协商工具”项目里常有各种缩写比如 LIS、BI、SSO、API新读者看到时如果没人解释后面段落就全成了天书。风险更好理解它写的是项目启动时就知道的不确定因素比如“培训数据从老系统迁移可能存在字段缺失”“第三方审批接口的响应时限未书面确认”。把风险放进概述不是为了吓人而是为了提醒读者看后面相应章节时带着问题。这三块平时不需要太长但必须真实。尤其是术语部分别只放高大上的学术名词要把内部常用黑话也列进去。比如团队内部常说“打平”意思是“数据拉平对齐”如果新人不了解理解就会产生偏差。3. 目标不是写出来而是定出来从“要什么”到“不要什么”3.1 目标书写的“动词陷阱”我刚带项目时最喜欢玩一个游戏把目标句子中的动词全部圈出来然后数一数有多少是无监督动词。什么叫无监督动词就是“优化”“提升”“加强”“完善”“促进”它们后面必须跟一个可观测对象才能落地。如果写成“优化培训管理流程”你无法验收如果写成“将培训报名操作步骤从6步压缩到3步”任何人都能判断做没做到。所以我给团队立了一条规矩目标句里不允许出现无监督动词除非在同一句话里给出了测量方法。这句话值得打印出来贴在工位上。你可以看下面这个对比表格不合格目标合格目标提升培训管理效率将培训报名平均耗时从5分钟降到2分钟加强数据准确性将学分录入错误率从5%降到0.5%以下改善用户体验将关键操作路径的页面响应时间从3秒降到1秒以内完善报表功能新增并上线12张标准经营分析报表合格目标都自带“仪表盘”。没有仪表盘的目标写得再漂亮也只是愿望清单。3.2 非目标把“No”明确写出来很多项目的范围蔓延根源不在范围章节而在“非目标”没写。不做什么其实比做什么更能定义项目的边界。举个例子目标非目标理由支持课程在线报名与学分自动累计不做复杂排课系统排课由线下运营团队维护本期只做打通提供管理员端数据导出不做可视化大屏大屏需求未冻结放到二期评估兼容主流移动端浏览器不做原生App公司当前策略是H5优先原生App无独立团队支撑这张表格比十段文字都有用。新成员看到后不会再来问你“要不要支持XX”他会先对照这份清单。如果你的概述里没有“非目标”这一节那说明你还没真正想清楚项目的边界后面被临时加需求的概率会非常高。3.3 一个可迁移的目标定义流程我每次写概述目标前会强制自己走四步列出项目干系人最近抱怨最多的三个痛点从业务方原话里提取关键词。给每个痛点配上可以量化的指标。指标可以是时间、次数、金额、成功率尽量别用“满意度”这种不容易设计的词。把“现状值”和“期望值”同时写出来。例如“现状每次培训反馈统计需3人天期望自动生成报表后降至0.5人天”。删掉那些“锦上添花”的目标。如果这个目标无法在六个月内落地就别写进概述宁可放到“后续规划”。这个过程看起来简单但关键在于“从业务原话提取”而不是从技术方案反推。目标应该来自问题不是来自功能。我见过有人从系统架构图反推出二十多条目标每条都是“支持XX模块、实现XX能力”那叫功能清单不叫目标。4. 范围边界是概述里最容易翻车的地方4.1 范围写得太粗等于没写我看到过这样的范围描述“本项目包含培训管理、课程管理、学员管理、数据分析。”这看起来列了四块但“数据分析”具体指什么是统计报表还是数据挖掘范围粒度太粗会等同于没说。读者会按自己的经验去猜测边界十个人能猜出十种版本。更严重的是范围太粗还给后期争论留下了空间。业务方可以指着“数据分析”四个字说“我要求做用户行为分析你没做所以项目不完整。”而项目组可以辩解说“我们理解的数据分析就是报表。”这种分歧如果放在概述阶段只需要多写一行“数据分析只包含固定报表不包含用户行为分析探索”就能避免。4.2 范围写得太细文档会迅速过期反过来也有团队把范围写到“按钮颜色”“提示文案措辞”。短期内固然清晰但系统界面一调整概述就失效最后变成一堆没人维护的废料。概述里的范围应该停在“模块级”或“能力级”描述这个模块负责什么、依赖什么而不是描述界面元素。例如培训管理负责培训项目的创建、发布、报名、签到、学时记录依赖组织架构数据来自主数据系统。这个粒度就比较合适。它告诉读者模块的大职责和依赖关系但不会因为某个按钮改了颜色就需要更新。把控粒度是个手感活我的经验是如果你写范围时犹豫“这条是不是太细了”那就把它从概述里删掉放到对应的章节里去。4.3 用“包含、不包含、边界”三份清单锁住我自己的习惯是在概述里用三个短清单描述范围包含列出本项目明确交付的能力模块。不包含列出经常被误认为属于本项目的功能。边界说明和周边系统的关系比如“本系统不存储组织架构只通过接口读取当组织架构更新时实时同步延迟不超过30分钟。”有了这三个清单评审会上的大量争论都能前移到文档阶段解决。因为“不包含”清单的存在干系人看到自己关心但没有被纳入的功能时会提前提出异议这比开发到一半再改要好得多。我有一次写“不做原生App”业务负责人当场表示反对后经过讨论确认web端已经满足场景才把这个分歧固化下来。如果我没写“不包含”这个问题可能要拖到测试阶段才爆发。5. 概述也要版本控制文档活不活得下去全看这里5.1 概述的维护人要唯一大多数项目文档死了不是因为没人读而是因为没人改。概述更是重灾区。一份概述写完之后如果项目发生变化没人负责更新六个月后再看它描述的系统已经和现实完全对不上了。我建议在概述开头标注“维护人”且只能有一个人。这个人通常由项目经理或技术负责人兼任。维护人的职责不是每次变更都去改正文而是判断这个变更是否会动摇概述中的任何一句陈述——比如目标改了、范围边界改了、核心术语含义改了。只要有一点变化就必须立刻更新概述并记录日期。如果只是某个Button进不了微调那完全不用管。这个判断能力比实际动手改文档更重要。5.2 变更行为要回写到版本历史很多人觉得版本历史只是形式主义但它其实是概述“保真”的关键。没有版本历史读者不知道当前段落是何时写的也不知道为什么要改。一张简单的表格就能解决版本日期修改人修改说明v0.12024-02-01张三完成初稿培训模块范围待业务确认v0.22024-02-20李四增加非目标“不做可视化大屏”补充术语表v0.32024-03-05张三目标指标调整报表耗时从0.5人天改为0.3人天这张表支撑了文档的可追溯性。新成员问“为什么当初不做大屏”不看聊天记录只看版本历史就能明白。我建议把“和概述对齐”纳入项目例会比如周会第一项议程固定为“概述是否需要更新”。不需要时十秒跳过需要时当场合入。这个动作看似琐碎执行起来效果极其明显。5.3 概述不更新会带来真实返工讲一个我踩过的坑。曾经有个项目第一期说好不做“权限审批流”所有审批走邮件。结果中途一个关键客户提出要求团队临时加了审批流并成功上线。功能做完了但概述里的范围依然写着“不做权限审批流”。半年后二期启动新来的产品经理基于旧概述做规划又投入三个人评估审批流的可行性相当于把已经做过的事重新设计了一遍。发现真相的那一刻整个团队都沉默了。这就是概述不更新的代价你以为文档只是旧实际上它会直接导致后续决策浪费真金白银。所以我现在对概述的版本历史特别敏感。它不是用来向上汇报的装饰而是项目记忆的一部分。6. 一个可以直接套用的概述模板附注释与避坑清单6.1 模板的核心结构下面是我目前在项目文档中实际使用的概述模板可以直接复制过去改成自己项目的。注意每个部分后面的“写法提示”才是重点。# 01 概述 ## 1.1 文档信息 - 维护人[姓名] - 最近更新日期[日期] - 适用读者[项目经理 / 开发 / 测试 / 业务方 / 新入职成员] ## 1.2 背景 [为什么是现在做这个项目出现了哪些具体问题带来什么业务影响用3~5句话描述不要泛化。] ## 1.3 目标 - G1[可验证目标1含基线值和期望值] - G2[可验证目标2含基线值和期望值] - G3[可验证目标3含基线值和期望值] ## 1.4 非目标 - N1[明确不做的功能或边界] - N2[明确不做的功能或边界] ## 1.5 范围 - 包含[模块/能力清单按系统业务模块组织] - 不包含[易被误认为在本项目内的功能] - 边界[与外部系统的依赖关系、数据流向、时效约束] ## 1.6 术语表 | 术语 | 解释 | |---|---| | XX | 指什么注意和相近概念的区别 | ## 1.7 风险与开放问题 - R1[已知风险] - R2[待确认问题]你看整个模板里最长的地方其实是“术语表”和“范围”。背景、目标、非目标都要求短而准。概述不是用来提供完整细节的它是用来让读者建立全局地图的。细节必须放到后面的章节。6.2 各部分篇幅建议背景控制在100字左右。如果超过150字就要怀疑是不是在写行业报告。目标与非目标目标3~5条非目标2~4条每条不超过30字。范围包含、不包含、边界各5~10项每项不超过一行。术语表只收新读者可能会困惑的不要收“系统登录”这种常识词。风险列已知事实不要列臆测。这些数字不是硬性规定但当你发现“概述”章节比后面所有章节都长时大概率是写偏了。概述应该短到新读者愿意读完又长到能回答核心问题。我见过一个极端例子某个文档“01_概述”写了四十页几乎把验收测试用例都放进去了结果根本没人读。文档的可用性和完整性需要平衡而概述明显应该偏向可用性。6.3 写完之后的自检清单我一般在提交文档前会再过一遍这份自检清单它帮我抓出过不少问题读完概述能不能说出项目“不做什么”目标里所有动词是否都能被客观测量如果删掉背景段落目标和范围是否仍然成立术语表里的缩写是否至少在当前文档的首次出现处有对应解释是否指定了唯一的维护人最近一次项目变更后概述里是否有过期的描述如果这六条里有一条不满足我就会改完再提交。虽然每次都多花十几分钟但它能省掉后面无数次的解释和纠偏。特别是最后一条我吃过太多亏了。有时候只是因为改了某个接口字段的名称却忘了同步到概述术语表导致新人在对接时拿旧字段名去查代码白白浪费了两个小时。这算是一个从实践中沉淀下来的概述写作框架。我最初也是被人问“你文档里写的目标到底怎么验收”时被迫开始一点点修正后来才形成现在这版结构。项目类型会变但这几个模块和原则几乎没有变过。如果你现在正要去写“01_概述”不妨先别急着打开空白文档花十分钟想清楚读者是谁再把这个模板填进去效果会好很多。
