程序员编写文档的 10 个技巧

编写好的文档在软件开发领域具有重大意义。文档是概述特定问题陈述、方法、功能、工作流程、架构、挑战和开发过程的书面数据或指令。文档可以让你全面了解解决方案的功能、安装和配置。

文档不仅是为其他人编写的,也是为自己编写的。它让我们自己知道我们以前做过什么,这有助于我们在发展它们时抓住确切的心态和想法。记录完善的计划使团队成员能够高效协作,减少团队花在弄清楚如何执行任务并让他们遵循既定工作流程上的时间。它可以帮助您和其他人理解实现细节,从而更容易维护或调试程序。

这里,我们将分享一些编写文档的技巧及常用工具,希望对大家有所帮助。

1.从了解问题开始


在制定解决方案之前先了解问题,这使我们对问题本身有了深刻的理解,并将它们写下来将有意识地开辟开发有效解决方案的可能性。清晰地定义和阐明问题有助于您确定问题的根本原因及其潜在影响。它还有助于与其他人(例如团队成员、审阅者和文档的其他潜在读者)沟通问题。

2.了解你的读者

当谈到编写好的文档时,我们需要考虑的关键事情之一是了解您的读者是谁,并据此进行编写。就像熟练的作家根据目标受众定制自己的作品一样,开发人员通过了解读者的潜力来编写文档也非常重要。我们可以做到这一点的方法之一是使用某些读者容易理解和掌握的语言和术语。

3.记录你未来的决定

使用此技巧的理想时间是当您要从编码中休息一下时,但您需要确保记住项目的流程。例如,您做出的逻辑、设计和架构决策。在捕捉特定发展历程的同时,跟踪您过去做出的决定或选择至关重要。这将极大地帮助你在休息后掌握确切的心态或状态。需要根据适当的理由来跟踪决策(您为什么做出选择?)。例如:

“决定:我们选择集成 PostgreSQL 数据库以实现高效的数据存储。

理由:PostgreSQL 因其强大的可靠性、可扩展性和广泛的功能而成为理想的选择。该数据库的 ACID 合规性保证了最大的数据一致性和完整性,这是我们项目成功的一个重要方面。此外,PostgreSQL 对高级查询功能的卓越支持及其可扩展性使我们能够无缝处理和分析大量数据。”

4.记录要点

记录要点是指跟踪所有的参考链接、文档和研究来源,以便开发人员更容易快速、轻松地访问资源,而不是长时间搜索特定文档或资源。如果实施得当,这可以节省数小时的时间。我们必须更加强调保留重要细节以供将来参考,因为它能够节省大量开发、维护甚至更新特定代码版本的时间。

5.保持简单、清晰、不言自明

文档应该易于读者理解。我们必须把构建模块的功能和逻辑解释得非常清楚,这有助于模块的进一步开发、维护和升级。我们必须尽可能保持文档干净且有条理。使文档本身不言自明至关重要。在记录程序的复杂部分时,建议在文档中添加示例代码,并真正尝试分解代码并使读者清楚这一点至关重要。正如我们之前讨论的,您的文档将覆盖广泛的人群,因此,您对文档的文字和结构的选择必须清晰,并向读者展示清晰的感觉,这一点非常重要。

6.共同创建

创建和维护文档不应该是一个单独的责任。创建文档的工作应该众包,原因有很多,主要是为了分配员工的工作量,这允许所有其他贡献者表现出对项目的主人翁意识。来自不同部门或领域的贡献者的参与将使我们能够创建整体且全面的文档。

例如,开发人员可能会在文档中贡献技术见解,而业务利益相关者则提供项目的目标和未来方面。总体而言,通过众包文档工作,您可以利用团队的集体知识和专业知识,从而生成更广泛、更准确且得到广泛认可的文档。

7.遵循统一的格式

我们需要在整个文档中遵循类似的格式化技术,以确保它易于理解,并允许读者轻松浏览内容并有效地获得有用的见解。如有必要,我们必须使用标题、副标题、要点和表格正确格式化文档。这些使我们能够保持文档的可读性。通过遵循统一的格式,我们可以创建有凝聚力且用户友好的文档。

8.使用图表和视觉效果

在文档中包含图表和视觉效果可以极大地提高读者的理解和参与度。更容易直观地解释复杂的逻辑和实现。图表、流程图和图表等视觉表示有助于以清晰简洁的方式说明流程、系统或数据。像这样的视觉表示作为一种通用语言,可以克服语言熟练程度或技术专业知识等障碍。在合并图表时,请确保添加清晰简洁的标签并保持一致性,以避免读者不必要的混淆。永远记住,图形应该增强书面内容,而不是完全取代它。应谨慎使用它们,重点是更有效地传达复杂或重要的信息。例如

9.在开发的同时编写文档

人们通常在开发阶段之后编写文档,这是一种常见的误解和不好的做法,这不仅使文档阶段变得更加复杂,而且还导致文档中出现很多错误信息。在这种情况下,回忆开发阶段的重要信息和细节就变得具有挑战性。此外,开发后创建文档会增加误解和误解扩散的可能性。如果没有实时文档,开发人员可能会诉诸个人解释或假设,导致实际实现与文档信息之间不一致。

10.审核最终版本

在项目的最后,一定从从头至尾彻底审核文档。因为会来回参与开发和文档,我们的文档可能缺乏所需的结构。最后,调整一些东西并重组文档可以使其成为格式良好且相对更好的文档。

最后的话

常见编写文档的网站有GitBook、Document360,要创建图表和流程图,您可以使用:微软Visio、XMind。总之,每个开发人员都应该牢牢掌握编写文档的技巧。文档是一种有用的工具,可以提高生产力、协作和知识转移,而不仅仅是事后的想法或例行任务。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/26507.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

大数据Flink(五十八):Flink on Yarn的三种部署方式介绍

文章目录 Flink on Yarn的三种部署方式介绍 一、​​​​​​​Session模式

F5 LTM 知识点和实验 12-使用规则和本地流量策略定制应用程序交付

第十一章:iapp(忽略) 第十二章:使用规则和本地流量策略定制应用程序交付 用最简单的术语来说,iRule是在网络流量通过BIGIP系统时对其执行的脚本。其思想非常简单:规则使您能够编写简单的网络感知代码片段,这些代码以各种方式影响您的网络流量。无论您是希望以BIG-IP内置…

2 Vue使用v-bind来代替{{}}取值

注意!当两个具有共同id的标签都要从数据层拿值时,需要使用div标签,赋予他们共同的id,不然其中有一个会拿不到数据! v-bind用来绑定前标签的属性,然后对属性赋值。{{}}用来对前后标签中的文本赋值。使用方法…

前沿分享-100 μAh 微型电池

这是SMD 组件形状的固态锂离子微型电池,容量高达 100Ah,在22年的慕尼黑电子展上出现过。 因为是可重复使用的,未来该产品甚至有机会取代容量更高(例如100 Ah 时)的不可充电硬币电池。 一般应用于超低功率的传感器&…

宋浩概率论笔记(四)数字特征

本帖更新数字特征,包含期望、方差、相关系数等,要点在于记忆性质中的各种公式,遇到题目时能迅速利用已知条件计算答案。

IDEA删除本地git仓库、创建本地git仓库、关联其他仓库并上传

IDEA删除本地git仓库、创建本地git仓库、关联其他仓库并上传 删除本地Git仓库 创建本地Git仓库 关联其他仓库并上传 要在IntelliJ IDEA中删除本地Git仓库并创建新的本地Git仓库,以及关联其他仓库并上传,请按照以下步骤进行操作: 删除本地G…

leetcode--每日一题--822--344(使用异或来进行数据交换)

822.翻转卡片游戏 在桌子上有 n 张卡片,每张卡片的正面和背面都写着一个正数(正面与背面上的数有可能不一样)。 我们可以先翻转任意张卡片,然后选择其中一张卡片。 如果选中的那张卡片背面的数字 x 与任意一张卡片的正面的数字都…

文字转语音

键盘获取文字,转化为语音后保存本地 from win32com.client import Dispatch from comtypes.client import CreateObject from comtypes.gen import SpeechLib speakerDispatch(SAPI.SpVoice) speaker.Speak(请输入你想转化的文字) datainput(请输入:)#s…

DROP USER c##xyt CASCADE > ORA-01940: 无法删除当前连接的用户

多创建了一个用户,想要给它删除掉 一 上执行过程,确实删除成功了 Oracle Database 12c Enterprise Edition Release 12.1.0.2.0 - 64bit Production With the Partitioning, OLAP, Advanced Analytics and Real Application Testing optionsSQL> DR…

第一百零六回 数据共享(状态管理)总结

文章目录 知识回顾知识总结经验分享 我们在上一章回中介绍了全局共享数据相关的内容,本章回中将对这些内容做总结.闲话休提,让我们一起Talk Flutter吧。 知识回顾 数据共享也叫状态管理,主要通过InheritedWidget类实现,不过它局限…

Self-Attention、transformer代码、word2vec理论(skip-gram、CNOW)、近似训练 (第十三次组会)

@[TOC](Self-Attention、transformer代码、word2vec理论(skip-gram、CNOW)、近似训练 (第十三次组会)) Self-Attention相关 Transformer代码

JVM之类加载与字节码(二)

3. 编译期处理 什么是语法糖 所谓的 语法糖 ,其实就是指 java 编译器把 *.java 源码编译为 *.class 字节码的过程中,自动生成 和转换的一些代码,主要是为了减轻程序员的负担,算是 java 编译器给我们的一个额外福利(给…

c++实现Qt信号和槽机制

文章目录 简介信号槽信号与槽的连接 特点观察者模式定义观察者模式结构图 实现简单的信号和槽 简介 信号槽机制与Windows下消息机制类似,消息机制是基于回调函数,Qt中用信号与槽来代替函数指针,使程序更安全简洁。  信号和槽机制是 Qt 的核心…

redis原理 2:交头接耳 —— 通信协议

Redis 的作者认为数据库系统的瓶颈一般不在于网络流量,而是数据库自身内部逻辑处理上。所以即使 Redis 使用了浪费流量的文本协议,依然可以取得极高的访问性能。Redis 将所有数据都放在内存,用一个单线程对外提供服务,单个节点在跑…

【小沐学NLP】在线AI绘画网站(百度:文心一格)

文章目录 1、简介2、文心一格2.1 功能简介2.2 操作步骤2.3 使用费用2.4 若干示例2.4.1 女孩2.4.2 昙花2.4.3 山水画2.4.4 夜晚2.4.5 古诗2.4.6 二次元2.4.7 帅哥 结语 1、简介 当下,越来越多AI领域前沿技术争相落地,逐步释放出极大的产业价值&#xff0…

【机密计算-大厂有话说】AMD

基于 VirTEE/SEV 的 SEV-SNP 平台证明 刊号 58217,版本 v1.2,发布于 2023.7 1. 介绍 VirTEE/sev 工具箱提供了一套基于 rust 语言的简单易用的 API 来访问 AMD EPYC 处理器内的安全处理器,这个库已经早已经支持传统的 SEV 固件,最…

荐读 | 《揭秘云计算与大数据》

当我们回顾过去几十年的科技进步时,云计算和大数据在现代科技发展史上无疑具有里程碑式的意义,它们不仅改变了我们的生活方式,而且对各行各业产生了深远的影响。 在这个数字化时代,云计算和大数据技术已经成为推动全球发展的关键…

SQL与NoSQL概念(详细介绍!!)

先搞清楚全称 SQL全称为Structured query language ,即结构化查询语言,可以把他理解为一门特殊的编程语言。 那么nosql是什么意思呢?这里的no并不仅是not,而是not only的意思,所以nosql全称应该是Not Only Structure…

线程池优雅关闭

背景 线程池是日常我们写代码时经常打交道的知识点了,围绕线程池除了core核心线程数和最大max线程数的知识点外,我们一般会忽略然而却绕不开的问题时如何关闭线程池 如何关闭线程池 首先从优雅关闭线程池代码说起: public boolean graful…

当编程遇上AI,纵享丝滑

目录 前言 一、提出需求 二、检查代码 三、进一步提出需求 总结 前言 自从CHATGPT火了以后,我发现我身边的人再也不怕写报告了,什么个人总结,汇报材料,年度总结,伸手就来(反正哪些报告也没人看&#x…