略谈为什么要重视文档写作

简介: 略谈为什么要重视文档写作

一、背景

 

今天在知乎上看到一篇《作为IT行业过来人,你有什么话想对后辈说的?》问题的答案,其中一小段摘录如下:

image.gif

非常值得在这里给大家分享一下。

二、感悟

2.1 亲身体会

见过很多刚毕业的同学缺乏工作经验又急于表现,为了尽快做完项目,在没有了解清楚相关背景和价值,没有做好完整的技术方案时,就着急开始编码。导致很多项目后面会有推倒重来的情况,也没有充分自测的意识,导致项目质量也不是很高。

这或许就是所谓的“欲速则不达”吧。

2.2 重视设计

这里所说的写文档更准确说应该是编写技术方案文档。

在技术方案文档中,将业务逻辑梳理清楚,设计好核心功能的技术实现,梳理好依赖的接口,画清楚系统之间、接口之间的调用关系,考虑清楚各种异常场景等。

然后对技术方案进行评审,让其他经验丰富或者了解该块业务的同事提提建议,对方案进行优化。

当技术方案设计清楚并评审通过,然后再编码,心里就会非常有底。

方案设计合理,编码只是一个时间问题。

如果编码完成后能进行充分自测,并进行代码评审,那么项目质量应该不会出现大问题。

2.3 百分比问题

文中提到,设计应该花 80% 的时间,编码和调试应该花 20% 的时间。

我不是特别认同这个百分比,实际工作中,比如10天编码的项目,可能要2-3天熟悉需求,然后进行技术方案设计。

如果把这个百分比当做是重要性我道是更倾向于认同。

大家要抓住重点,文章想表达的是技术方案设计的重要性。

三、总结

本文虽然内容不多,但在此呼吁大家在动手之前一定将核心的逻辑,核心的方案想清楚,尽可能落到文档中。

在项目编码完成之后,一定要自己先自测,自己先审查一下自己的代码,然后再提测。

在提测期间,强烈推荐通过 tail -f  error.log  或者其他方式随时观察错误日志,项目相关问题早点修复掉,而不是等测试找到你再去改。

这种意识非常重要,希望刚工作不久的同学一定要重视。

PS: 改天有时间我会写一下如何写技术方案,如何写提测文档。


相关文章
用 ChatGPT 编写英文技术文章要自己多审核,否则容易被严谨的同行喷
用 ChatGPT 编写英文技术文章要自己多审核,否则容易被严谨的同行喷
|
3月前
|
人工智能 自然语言处理 算法
如何利用【抖音-豆包】进行文章撰写与技能学习
如何利用【抖音-豆包】进行文章撰写与技能学习
92 1
|
2月前
|
机器学习/深度学习 人工智能 搜索推荐
谈谈内容创作中的UGC、PGC、AIGC,在创意设计领域的应用与进化
在数字化时代,内容创作经历了从UGC(用户生成内容)到PGC(专业生产内容),再到AIGC(人工智能生成内容)的转变。UGC打破了传统边界,让每个人都能参与创作,但质量参差不齐;PGC代表专业水准,提供高质量内容,但成本高且制作周期长;AIGC借助AI技术大幅提升效率,实现个性化定制,但面临版权、伦理和情感表达的挑战。Adobe国际认证等专业资格成为了衡量设计师能力的新标准,帮助设计师适应这一变革并引领创新。三种模式相互补充,共同推动创意设计领域不断发展。
|
4月前
|
项目管理
技术方案撰写之道:实用技巧与方法
本文探讨了如何撰写技术方案,强调了考虑方案的相关方、关键指标、目标受众和预期收益的重要性。文章提出了写作框架应清晰、表达生动、具有美感,并指出好的方案应实现共赢、系统规划和显著效益。写技术方案时,需明确问题、深入分析需求、设定合理目标、设立度量标准、专业设计方案、规划执行路径并有效项目管理,确保方案的成功实施和收益。
528 0
|
程序员 测试技术 API
程序员不撰写代码注释和文档的十大理由
在软件开发的世界中,撰写代码注释和文档通常被认为是一项重要的工作,它可以帮助其他开发者理解你的代码,更容易地维护和扩展它。然而,在实际操作中,很多程序员却选择不写注释或文档。以下列出了程序员们在实践中经常提到的十大理由,这些理由不仅揭示了他们对于撰写文档和注释的观点,也反映出软件开发行业中一些深层次的问题。
145 1
程序员不撰写代码注释和文档的十大理由
|
人工智能 自然语言处理 Python
中文竞技场模型测评——针对写作创作、代码编写、知识常识相关的测评
本次主要是针对中文竞技场大模型的写作创作水平进行评测,考察续写、分析、总结等几个方面的能力。
|
语音技术
如何用ChatGPT写专业方向的科普内容?
该场景对应的关键词库(13个): 目标用户、科普内容、生活问题、医疗类型、科普文章、病情症状、通俗性、专业名词、背景资质、权威领域、执业范围、证言人、内容形式。
152 0
如何用ChatGPT写专业方向的科普内容?
|
算法 程序员
在你写的代码中寻求安宁的艺术
在编程中,代码的质量和可读性对于程序员来说至关重要。而寻求代码中的安宁,则是一种注重代码的整洁和优雅,追求高效和可维护性的艺术。本文将探讨在编写代码时如何寻求代码中的安宁,并提供一些实践建议。
62 0
|
小程序
近期写作回顾
这算是经常写作的一个好处吧!它会帮助你记录下所干过的事情。我们的记忆并不长久,尤其是对于那些并不是很重要的事情,不信你试着回忆一下,中旬自己都干了些什么,是不是根本就想不起来了。
68 0
|
JavaScript 搜索推荐 前端开发
软件工程师文档写作最佳实践
软件工程师文档写作最佳实践
215 1
软件工程师文档写作最佳实践