V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
hxndg
V2EX  ›  程序员

如何写技术文档

  •  
  •   hxndg · 2021-03-22 22:07:59 +08:00 · 1135 次点击
    这是一个创建于 1345 天前的主题,其中的信息可能已经有所发展或是发生改变。

    前言

    我这两天翻了下国内的一些文档规范,发现基本都是规范格式,缺乏对写文档的通用思路,所以写一个通用的写文档思路。

    写前准备

    写之前要做的东西并不多,大的方面就两个:

    • 规范术语:规范技术文档中用到的专业术语,中文互联网一个导致谬误丛生的原因就是各种同义词乱飞,因此很有必要再一开始就确定专业术语,约定隐喻是什么。如果中文不好表达,可以一开始就使用英文规范
    • 对阅读者建模:文档最终是要给人看的,表达的方式要根据阅读者的身份变化。从我个人的角度来看,如果是给 QA/PM 看的文章,那么务必保持术语的通俗易懂,尽量使用平易的语言,同时逻辑递增要保持渐进性,不能上来就什么“hash”加密,

    写作要点

    编写文档的时候,注意的要点要跟随文章类型变化。但是有一些通用的方法可以使用。

    • 文档编写者首先要具体地陈述问题,换言之要写出原有功能 /设计的局限性,该功能处于那一层?为什么要在本层做?有什么不足?这点写出来,就可以继续向下进行。
    • 因为有不足,自然就会有客户提出需求,需要给出来客户最开始的原始需求是什么,需求经过了什么变化,为什么会有这种变化,如果是多方需求要写清楚每一方需求的变化。
    • 客户的需求阐明了,下一步就是简述我们做的工作是什么,设计时考虑了哪些细节。一般我写这块的时候都是按照原有协议层次的方式来进行描写 1 每层具体提供了什么功能,可以依托现有协议地层次,或者依托功能划分地层次进行描述; 2 给出每一层我们依赖地第三方 /基础功能,并说明每层对上层提供地保证和利用的下层的依赖。层次之间的够通也需要说清楚。

    写后总结

    写后总结并不是总结这次写的哪里不好,而是一个总的收尾工作。同样需要考虑阅读者是谁来决定怎么写

    • 阅读者是客户,那么需要给出详尽的用户使用场景及提示信息,交互信息
    • 阅读者是 QA,需要给出具体的 TestConsiderration 与针对的 TroubleShooting
    • 阅读者是开发,需要给出系统设计的基本逻辑,给出系统设计时的取舍。
    • 无论阅读者是谁,最后都要加上 Security Consideration,即安全性考虑。

    结尾碎碎念

    如果觉得上面的思考过于麻烦,不如使用机械的手段,直接将文档分为:术语规范;问题描述;客户需求;详尽描述; TestConsiderration ;。。。等部分,来减少思考的麻烦。

    目前尚无回复
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   4191 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 23ms · UTC 05:23 · PVG 13:23 · LAX 21:23 · JFK 00:23
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.