学习写技术文档

    一直都没有写过正规的技术文档,正在努力学习中。如何准确有条理并且简明扼要的描述一件事情还有如何抓住重点,是我要学习的主要内容。

转一点资料:

总结一下五条原则:
一·不写想当然的文档。
二·不写只是由于格式或者规范要求你写的文档,而是写确实有内容文档。
三·写简明扼要,重点突出,与阅读者水平相当的文档。
四·写明确无无疑义的文档,且为此制定标准,并是大家都遵守此标准。
五·写你或者别人认为需要的文档,而不是规范或者标准要求你写的文档。
文档需要反映的是实实在在的问题,而不要建立在想当然的基础上。
文档需要规范吗?需要。需要格式化吗?需要。但是文档更需要的是内容,没有内容的文档不是垃圾是什么。所以第二条原则就是写有内容的文档,而不是文档规范和格式要求你写的文档。
文档是干吗的,用来收藏的?用来评级的?用来对付人的?如果你都给予肯定的回答,那么你干脆就去搞文档工程,不要来搞软件工程。文档最终的目的还是要人去阅读,要别人通过阅读理解自己所要传递的信息,要自己以后看从前的文档可以回忆当时的所表达的信息。如果你可以直接把这些信息传递给需要传递的人,你就没有必要写文档。如果传递的信息混乱不明,繁琐不易阅读,或者信息量太大,不能很好的理解,那么你写的文档一样只是垃圾一类的货色。写文档不是写论文,不需要说理明确,引用准确,关键的是要可以传递信息。所以第三条原则是写文档要简明扼要,抓住重点,同时考虑阅读者的水平,不能给小学生写微积分,也不必给教授解释为什么2的3倍是6。
按照规范和格式写出来的文档才最不容易懂,因为你怎么能真的知道他要写的东西是他想写的东西。写文档最重要的是要有写文档的标准,而不是格式。比如如果你的需求说明书最后的版本上写着,A界面反映迅速,这显然可以符合规范和格式,但是确实是一个有百害无一疑的说明--当你的客户为1.5秒刷新不迅速而不付款的时候,你就明白你的文档多么愚蠢而无用。所以文档的写作第四条原则,就是写含义明确无疑义的文档,并且为此制定一个标准,同时人所有人都遵守这个标准。
其实写文档是一件简单的不能在简单的事情。就向我小时候写作文,冥思苦想左右不得要领,搜肠刮肚只能应付了事。而现在且下笔如飞,潇潇洒洒,动不动就千言万语。原因简单的不能在简单,因为当初写作为是不自愿的,现在做文章是自觉的;写作文是别人命题的,写文章是自己定题的;写作文是要有什么主题思想,要有格式,要字迹清除;而写文章只要你看懂就好,只要告诉了你我要告诉的东西就好。所以第五条原则就是写你认为需要的文档,而不是写别人要求你写的文档。当然这是在说你不应因为有个什么规范或者标准要求你去写一个什么文档,你就去写那么文档。而是说如果某些人需要那些文档来理解一些问题,那么你就需要写那些文档。  

  • 0
    点赞
  • 2
    收藏
    觉得还不错? 一键收藏
  • 2
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 2
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值