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

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

一、背景

 

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

image.gif

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

二、感悟

2.1 亲身体会

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

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

2.2 重视设计

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

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

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

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

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

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

2.3 百分比问题

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

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

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

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

三、总结

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

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

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

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

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


相关文章
|
11月前
|
人工智能 测试技术 Python
软件测试/人工智能|PPT不好写,问问ChatGPT
软件测试/人工智能|PPT不好写,问问ChatGPT
|
4月前
|
机器学习/深度学习 Kubernetes 云计算
技术文档工程师和技术翻译
- 阿里云智能集团招聘技术岗,位于杭州和北京。 - 技术文档工程师岗位要求包括独立编写代码能力、快速学习新技术、简化复杂技术概念、扎实的技术理解和良好的时间管理。 - 翻译工程师还需具备相关学历背景、技术翻译经验和云产品知识。 **团队成员分享:** - 昱心(南洋理工大学,机器学习)和骞腾(UIUC,计算机科学)分享了他们在技术文档岗位上的成长,涉及大模型和K8S等技术。 - 舟预(北京交通大学,信息管理)强调技术文档的重要性,认为它是阿里云对外的权威发言人。 - 天蒙(南开大学,信息与通信工程)提到工作中与代码的紧密联系,团队支持技术成长。
23842 24
技术文档工程师和技术翻译
|
3月前
|
SQL IDE JavaScript
"揭秘高效代码Review秘籍:如何像侦探一样挖掘隐藏错误,提升团队编程实力,你不可错过的实战指南!"
【8月更文挑战第20天】代码Review是软件开发中提升代码质量与团队协作的关键环节。本文详细介绍高效代码Review流程:从明确范围与标准开始,到逐行审查与工具辅助,再到积极沟通与闭环管理,辅以示例确保清晰易懂。通过实践这些步骤,不仅能减少错误,还能促进知识共享,为构建高质量软件打下坚实基础。
63 2
|
5月前
|
人工智能 自然语言处理 算法
如何利用【抖音-豆包】进行文章撰写与技能学习
如何利用【抖音-豆包】进行文章撰写与技能学习
155 1
|
程序员 测试技术 API
程序员不撰写代码注释和文档的十大理由
在软件开发的世界中,撰写代码注释和文档通常被认为是一项重要的工作,它可以帮助其他开发者理解你的代码,更容易地维护和扩展它。然而,在实际操作中,很多程序员却选择不写注释或文档。以下列出了程序员们在实践中经常提到的十大理由,这些理由不仅揭示了他们对于撰写文档和注释的观点,也反映出软件开发行业中一些深层次的问题。
158 1
程序员不撰写代码注释和文档的十大理由
|
人工智能 自然语言处理 Python
中文竞技场模型测评——针对写作创作、代码编写、知识常识相关的测评
本次主要是针对中文竞技场大模型的写作创作水平进行评测,考察续写、分析、总结等几个方面的能力。
|
语音技术
如何用ChatGPT写专业方向的科普内容?
该场景对应的关键词库(13个): 目标用户、科普内容、生活问题、医疗类型、科普文章、病情症状、通俗性、专业名词、背景资质、权威领域、执业范围、证言人、内容形式。
166 0
如何用ChatGPT写专业方向的科普内容?
|
算法 程序员
在你写的代码中寻求安宁的艺术
在编程中,代码的质量和可读性对于程序员来说至关重要。而寻求代码中的安宁,则是一种注重代码的整洁和优雅,追求高效和可维护性的艺术。本文将探讨在编写代码时如何寻求代码中的安宁,并提供一些实践建议。
71 0
|
人工智能 自然语言处理 搜索推荐
「译文」用ChatGPT助力SEO工作
「译文」用ChatGPT助力SEO工作
141 0
|
JavaScript 搜索推荐 前端开发
软件工程师文档写作最佳实践
软件工程师文档写作最佳实践
241 1
软件工程师文档写作最佳实践