InfoQ 不写文档你就输了( 二 )
文章图片
最重要的是 ， 文档应该是根据用户而不是开发人员的思考过程来编写的 。 以这种方式处理你自己的文档 ， 将为你提供一个更好的视角来组织自己的代码 。
2.遵守标准
在添加与代码内联的文档时 ， 请使用代码编程语言所期望的标准 。 我们应该总是解释每个函数、变量以及函数返回的值都是什么意思 。 下面是一个很好的PHP内联文档示例 。
以下是使用PHP、JavaScript和CSS的最佳实践来格式化内联文档的一些参考：
PHP：WordPress的PHP文档标准
JavaScript：UseJSDoc
CSS：CSSDoc
如果你使用的是SublimeText ， 我建议你安装DocBlockr ， 它将用内联文档巧妙地预填充你的代码 。
3.图形元素
文档中应该多用图形元素 ， 它们比文本更直观 。 这些媒介很有用 ， 特别是当你使用图形界面构建软件时 。 你可以添加指向性元素 ， 例如箭头、圆圈或任何可以帮助用户直观地弄清楚如何完成这些步骤的元素 。
以下是Tower应用中的示例 ， 你可以从中汲取灵感 。 它们很好地解释了如何用优雅的方式来做版本控制工作 ， 比纯文本命令行更容易理解 。
4.分区
你可以考虑将文档中的一些内容包装在项目符号列表和表格中 ， 因为这样可以让用户更容易浏览较长的内容 ， 更方便快速定位 。
添加目录 ， 并将文档拆分为一些容易理解的部分 ， 同时要让各个部分与接下来的内容保持关联 。 内容应该简短明了 。 以下是Facebook中一份组织良好的文档示例 。
我们可以点击目录元素 ， 直接跳转到对应内容 。
文章图片
5.修订和更新
最后 ， 文档写好后要仔细查看文档中是否有错误 ， 并在必要时 ， 或在产品、软件或库发生重大更改时修订文档 。 如果不随产品一起定期更新 ， 那么你的文档对任何人都是没用的 。
https://www.hongkiat.com/blog/why-documentation-essential/
【InfoQ 不写文档你就输了】点个在看少个bug
推荐阅读
- 极果果粉要哭了？苹果内部文档曝光，iPhone 12 双卡模式不支持 5G
- 威锋网|12双卡模式下无法启用5G，一份内部文档显示：目前iPhone
- 金山文档助力青岛疫情防控 安全高效赋能信息统计
- 电脑使用技巧Mac电脑如何使用MyZip压缩文件--帮助文档
- InfoQ12种Flutter开发工具推荐
- InfoQ一个IT时代的终结：109岁的IBM将分拆为两家公司
- InfoQ芯片断供，华为软件艰难补洞
- InfoQ不写文档你就输了
- InfoQ我是一位40岁的“老程序员”，我有一些想法
- |夏可叔叔扒产品——科颜氏超A面霜（推）