abap 帮助文档 中文_谷歌的软件工程 读书笔记（十）文档
码农的两大烦恼：
- 别人的代码没有文档
- 别人居然要求我给我的代码写文档
文档的质量差，数量少，甚至根本没有文档是软件工程面临的普遍问题。
什么是合格的文档？
任何对于代码的补充性文本都是文档，包括代码的注释。
为什么需要文档？
文档对于作者而言往往无法马上带来直接收益，然而就像测试一样，投资到文档里的投入最终往往会带来丰厚的回报。文档会拥有成千上万的读者，它一般会帮助回答以下的问题：
- 为什么会作出这样的设计决策？
- 为什么要以这样的方式来实现代码？
- 如果你自己看自己两年前的代码，你会问自己，我当时是怎么想的？
码农对于文档的轻视除了不能带来短期收益外，还有如下的原因：
- 码农认为写代码和写文档是完全不同的技能
- 码农认为自己并不擅长写作
- 写文档往往更困难，因为没有好的工具和流程的支持
- 文档被认为是额外的负担，而非使工作更轻松
好的文档收益如下：
- 帮助形成API
- 提供维护的路标，和历史的记录
- 让你的代码看上去更专业
- 帮助解答用户的问题
文档就像代码
文档和代码一样，需要保持清晰，准确，一致，避免出错。文档需要有维护者和所有者。
谷歌使用go/links来使文档的访问变得简单。
文档和代码仅仅的耦合，所以应该被看作是代码的一部分。
文档应该：
- 符合内部策略和规则
- 使用版本控制系统例如git
- 有明确的所有者或责任人
- 对文档的变更进行审阅
- 跟踪缺陷
- 定期评估
- 对准确性，新鲜度进行评估
了解你的读者
工程师写文档犯下的最大的错误就是以为文档是写给自己看的。记住写文档的时候要清楚的了解谁才是这个文档的读者。不一定要写出完美无暇的文档们，但是要写出适合读者阅读的文档。
需要考虑读者的不同方面
- 对编程语言掌握的程度
- 对领域掌握的程度
- 读该文档的目的
文档的类型
文档的类型包含：
- 参考文档，注释
- 设计文档
- 教程
- 概念文档
- 登陆页面
文档的审视
文档和代码一样，需要审视。
文档的审视需要考虑以下的内容：
- 从技术的角度审视准确性
- 从读者的角度审视清晰性
- 从写作的角度审视一致性
写文档的哲学
- 5W What/Why/Who/When/Where
- 开始/中间/结束
- 好文档的要素：完整，准确，清晰
什么时候需要技术写作者？
技术写作者(technical writer)并不意味着工程师就不用写文档了，他们可以从另一个角度来看待你的项目，作出一样的假定。这一点非常重要。
总结
和测试相比较，文档在谷歌受到的重视程度还是要低一些。测试可以自动化，而文档不可以。
要解决文档的问题，工程师和其组织必须承认，他们即是问题，也是解决方案。写好文档是工作的一部分。而这些文档会存在很长时间，被很多人阅读。好的文档不仅仅帮助那些阅读它的人，也会帮助他的作者。
abap 帮助文档 中文_谷歌的软件工程 读书笔记（十）文档相关推荐
- twitter推文不收录_如何使用Twitter书签保存推文供以后使用
twitter推文不收录 Khamosh Pathak Khamosh Pathak Twitter has a new Bookmarks feature that lets you private ...
- 度量相似性数学建模_数学之美读书笔记
2020年6月读,先通读一遍,随后为写读书笔记又重新读了一遍,收获颇丰,虽然没有很多数学或者编程方面的知识,但正如作者所说,这本书讲述的是道,而非术. 读这本书让我领略到了科学的趣味,并不是枯燥的敲代 ...
- 两条信号之间加电容_信号完整性SI读书笔记之一
微信公众号:硬核电子--一个只分享技术原创文的公众号. 本周项目较忙,没什么时间撰写文章.但即使这样,本人也不愿意随便从网络上搬运一篇文章过来凑数,因此,就分享一下比较久以前整理的有关信号完整性的读 ...
- abap 帮助文档 中文_一个13年ABAP老兵的建议：了解这些知识对ABAP开发有百利而无一害...
在Jerry之前的图片推送中,我提到了SAP社区上这样一篇博客: Proof of Concept: Deploying ABAP in Kubernetes https://blogs.sap.co ...
- python3.7怎么设置中文_解决 Bug · Python3.7.3官方文档 简体中文 · 看云
### 导航 - [索引](genindex.xhtml "总目录") - [模块](py-modindex.xhtml "Python 模块索引") | - ...
- python 打印xml文档树_[Python]xml.etree.ElementTree处理xml文档
需求: 在实际应用中,需要对xml配置文件进行实时修改, 1.增加.删除 某些节点 2.增加,删除,修改某个节点下的某些属性 3.增加,删除,修改某些节点的文本 xml源文件格式[例] path=&q ...
- 软件需求文档范例_【设计API系列】 一文了解常见的事件驱动APIs范例
最近几年, 很多种API范例涌现出来,目前比较流行的标准如REST, RPC, GraphQL, WebHooks 以及WebSockets等.但是大家大家真的对每一种都很了解吗?什么场景下适合用哪种 ...
- 写java接口的文档工具_【java】适合写接口文档的工具，或者文本语法
由于后端与前端使用ajax交互,后端写接口文档变得非常有必要.以前我习惯用word写接口文档,但是最近与同事合作编写后端,word并不适合使用svn工具做同步,因为svn.git等无法自动合并word ...
- python docx 合并文档 图片_使用python抓取大量简历文档内数据(word:docx;pdf;图片等）输出表格文件...
1. 文章背景描述: 近期公司有员工离职了,技术岗位的. 让HR招人,招聘进度也太慢了,实在等不及,就撸起袖子自己上.(之前从来没招聘过) 自己在某招聘网站注册后,花了若干人民币,短时间收到大量求职者 ...
最新文章
- Redis 延时任务（高手养成篇）
- Html5 绘制旋转的太极图
- 【深度学习】基于Pytorch的线性模型概念辨析和实现(二)
- 寻找kernel32.dll的地址
- 计算机对中断的处理是在用户态下进行的,电大本科生作业系统作业3与答案.doc...
- golang type 说明和使用
- PyTorch实现自由的数据读取
- 技术选择真的没有那么重要
- Qt学习笔记——打开并显示图片
- Spark Structured Steaming 聚合、watermark 以及 window操作，结合输出模式的研究总结
- junit可执行但控制层无法执行_解决junit5无法使用gradle test运行测试
- Xshell 6免费版
- innosetup 安装前、卸载前判断是否有进程正在运行转
- [数字图像处理]频域滤波(2)--高通滤波器，带阻滤波器与陷波滤波器
- 想法随笔——知乎段子
- 【第一组】第十五次冲刺例会纪要
- 重新测试Python读Excel文件xlsx的语言编码
- Mint UI—loadmore—Pull down下拉刷新将下拉刷新的箭头标志更换成其他图片（图文）
- 传统行业也很冷：星美影院欠债4个亿，关停140家分店
- 手把手教你使用Python网络爬虫获取音效信息