设为首页
收藏本站
切换到宽版
首页
Portal
论坛
BBS
图库
资讯
导读
Guide
动态
Space
排行榜
Ranklist
帮助
Help
记录
Doing
登录
立即注册
ROOT开源
»
论坛
›
ROOT资讯
›
范文
›
技术文档写作技巧
返回列表
发布新帖
技术文档写作技巧
IP属地:
四川省成都市
1048
1
[db:作者]
Lv.6
发表于 2023-5-29 01:39:58
|
查看全部
阅读模式
马上注册,结交更多好友,享用更多功能,让你轻松玩转社区。
您需要
登录
才可以下载或查看,没有账号?
立即注册
×
如何写一篇好的技术文档
最近在公司内部审查(Review) 一篇详细设计文档时,对于文档作者所写的文档 觉得很多地方需要改进。对于其中所存在的值得提高的地方,我想不是我们中国 软件行业的个别问题,相反,存在一定的普遍性。以下我列出了几个值得提高的 地方。
1) 文档的格式上存在不一致性的问题。格式有时是这样,有时是那样。一篇好 的文档我想不光是内容写得好,其格式是很重要的一部分。试想,如果我们拿到 了一篇格 式上写得乱七八糟的文档,这一第一印象会影响我们的阅读心情吗? 好的文档应当是从头到尾保持格式的一致性, 这不仅仅是一种美,更是专业性的 一种表现。
2) 写文档的作者不能很好的站在读者的角度去思考。要写出一篇好的支持文档, 作者应当站在读者的角度上去写。这简单的一句话,要操作起来,将其做好,还 真不是一件容易的事。在写文档时,如果不站在读者的角度去思考,很容易写 出一篇“自己一看觉得活活楚楚,别人一看却糊里糊涂”的文档。
3) 文档求长不求 精。一说到写文档,我不知是否有人将“文档应当长”当作是
文档的必要届性。对于这一点,我想正确的态度是:求精不求长。一篇好的文档, 应当写得简练易懂。 写文档的目的是什么?是为了让别人明白我们所要说明的
问题,要说明问题,并不需要一定将其写得长。一篇精炼的文档也意味着效率, 即读者花很少的时间就明白 我们想要表达的问题是什么。当然,从作者的角度 来看,要写一篇精炼的文档,那得花更多的时间去斟酌。
4) 图太少。有图不是一篇好文档的必要条件,但在不少情况下,用一幅图能很
好的表达我们的思想,不是有那么一句话吗“好图胜过千言万语”, 适当的采用 一些图,一方面能为文档增色,另一方面也能更好的向读者传达我们的意图。
好了,值得提高的点也提出来了,如何去做好呢?我想下面是我所能想到的一些 方法,在此,将与上面的提高点一一对应进行阐述。
1) 对于格式问题,找一篇自己觉得格式不错的文档进行模仿,并将其做成一个 棋板,每次写作时以这一模板为基础。
2) 写完以后,假设自己是读者多次阅读自己的文档。
这一点要做好还是很难的, 因为,我们很难完全站在读者的角度去读自己写的文档, 我们不知道自己所知的 哪些东西是读者所不知的,即很难界定与读者知识不对称的分界点。为了提高 这一点,我想我们写文档时,应当多问自己一些问题,比如,读者具有与我一样 的知识和经验 吗?如果没有,我应当写哪些以弥补这种信息的不对称性呢?我
写的这篇文档是基于一定的假设吗?如果是, 是否应当将这一假设在文档中交代 活楚呢?我所写的内 容是否都在支持文档的主题呢?是否存在正交问题(即答 非所问的问题)?等等。
3) 在文档写完后多问一问自己,这篇文档还能写得更简单吗?是否可以将一些
文字省去并用一幅图取而代之以达到使其简练的目的呢?不防时刻对自己说, 简
单也是一种美!
4) 学习(并精通)一些行业所需的图形语言和工具,并加以运用。比如,我们 软件行业的UMLM是很好的一种表达语言,且随着UML勺发展,其表达能力更加 的强 大。目前,业内有很我UML勺工具,找一个不错的就行了,比如 Visual Paradigm的UMLX具就不错,工具其实只是一种工具,关键是掌握UML只有我 们很好的掌握一种图形语言,我们才有可能随时加以运用,从而为我们 的技术 文档服务。当然,像Microsoft的Viso也是不错的绘图工具,这要看我们想表 达的是什么,从而加以灵活运用各种工具。
至 此就好了吗?不,还有很重要的一点是:我们需要在思想上做一些改变,这 种改变是什么呢?那就是:写出一篇好的技术文档是一个专业软件工程师的必要 素养!我 们必须抛弃那种软件工程帅只要能写出漂亮的代码就行了的思想,而 是要将“写好每一篇技术文档是专业软件工程师的必要素养”这一句话深入到 我们的骨髓当中 去,只有这样,我们所写的技术文档才会越来越好、才会越来 越专业。
“李云” 博客 /831344/168352
回复
使用道具
举报
提升卡
置顶卡
沉默卡
喧嚣卡
变色卡
千斤顶
照妖镜
电梯直达
评论
1
善渊
Lv.9
发表于 2023-5-29 02:44:20
手机端
|
查看全部
IP属地:
四川省成都市
靠谱
风起于青萍之末,浪成于微澜之间。跌谷底也要开花。沉海底也要望月。与其抱怨于黑暗。不如提灯向前行。
回复
使用道具
举报
照妖镜
返回列表
发布新帖
回复
高级模式
B
Color
Image
Link
Quote
Code
Smilies
您需要登录后才可以回帖
登录
|
立即注册
本版积分规则
发表回复
回帖并转播
回帖后跳转到最后一页
[db:作者]
Lv.6 化神
主题
1687
回帖
0
积分
1697
+ 关注
发消息
图文热点
RVC 实时声音变声器:一款基于AI的革新性语
769 人气
#工具
微信/QQ/TIM 防撤回多开补丁 RevokeMsgPatc
6 人气
#工具
B站视频下载工具 Bilidown 1.2.0
7 人气
#工具
聚合AI、犀利猫等通达信MPV1.2
6 人气
#工具
推荐话题
1
Topaz Video AI 4.2.2(智能视频无损放大)汉化简体中文版
2231 阅读
善渊
2
天盾网络验证离线版,带全套教程
1916 阅读
道法孜然
3
Topaz Gigapixel AI 7.1.0(人工智能图片降噪软件)简体中文汉化版
2104 阅读
善渊
4
【4.16 更新V1.2】支持多人配音、全局间隔、免费微软配音工具
1315 阅读
善渊
5
免费AI变声神器!多样音源任你选,让你的声音瞬间变身!
1168 阅读
善渊
最新发布
微信/QQ/TIM 防撤回多开补丁 RevokeMsgPatc
B站视频下载工具 Bilidown 1.2.0
聚合AI、犀利猫等通达信MPV1.2
dz(Discuz)修改网站标题Powered by Discu
官场小说
君当如青松,我当与君同 原文
央视网视频下载器 v5.1
永久基本农田查询平台
活跃会员
经常参与各类话题的讨论,发帖内容较有主见
关于我们
关于我们
加入我们
新闻动态
联系我们
服务支持
官方商城
成功案例
常见问题
售后服务
投诉/建议联系
908164873@Qq.com
让我们一起寻找开源的乐趣
转载复制,请保留来源地址
关注公众号
添加微信客服
Copyright © 2001-2024
ROOT开源
版权所有
All Rights Reserved.
网站地图
|
仅供演示
|
仅供演示
关灯
在本版发帖
扫一扫添加微信客服
QQ客服
返回顶部
快速回复
返回顶部
返回列表