开发人员写作》--成为会写作的开发人员的必读书！

有了人工智能对开发人员的帮助，仅仅写出优秀的代码是远远不够的。文档、技术博客、编写对用户友好的信息等等。 写作技巧是优秀开发人员的必备技能。

Kim 的这本书是一本实用指南，可以帮助开发人员在面对这些变化时从他们的写作中获得更多价值。 在这篇文章中，我们将总结每一章的主要收获，并讨论为什么这本书是开发人员的必读书。

"为开发人员写作 "一书概览

• 作者:Cheoljoo Kim
• 出版商：非公开
• 出版年份:2019
• 目标受众开发人员、规划人员、IT工作者以及其他任何需要写好文章的人。
• 特点:
  • 从代码内写作（变量名、注释）到代码外写作（技术博客、提案等）。
  • 提供实践范例和实用指导。
  • 从开发人员的角度出发，提供清晰实用的写作方法。

关键信息

1. 写作的重要性

- 为开发人员写作是一项基本技能，它不仅能编写代码，还能加强协作、沟通和解决问题。

2. 平衡代码和文档

- 清晰的文档与编写良好的代码同样重要。文档可以提高项目的生产力和可维护性。

3. 书写简洁明了

- 以读者为中心的写作方式会让你的技术内容更加有效。

4. 立即实际应用

- 本书中的原则和方法具体而实用，你可以立即付诸实践。

第 1 章：开发人员需要了解的编写基础知识

开发人员写作》第一章介绍了写作的基本理念和结构。

1. 准确性、简洁性和可读性

• 关键是要创建一个能够传达正确信息、摒弃杂乱无章、易于阅读的结构。
• 考虑读者的观点，分清主次，简明扼要地传达文章的关键信息。

2. 组织句子

• "(《世界人权宣言》) 金字塔结构建议
• 把重要内容放在前面，可以让忙碌的读者更容易掌握关键信息。

3. 选择格式

• 描述性、修改性、示意性等。 选择符合语境的写作格式。
• 例如，发布说明采用转述文体效果很好，而技术博客采用叙述文体效果很好。

第 2 章：通过命名和注释缩短开发时间

良好的命名和注释有利于团队成员之间的交流，也使维护工作更加轻松。

1. 命名规则

• 变量和函数名称应直观，并在团队中保持一致。
• 例如：totalVisitors（游客总数）比 visitorCount（游客人数）更容易搜索和理解。

2. 如何编写注释

• 必要时才写：写得好的代码本身就应该是一个注释。
• 描述背景：写出你为什么需要这段代码以及你的意图是什么。

示例

• 坏例子// 在计数中加一。
• 例如// 增加 1 个用户，以反映库存调整。

第 3 章：编写与用户交流的错误信息

用户友好型错误信息不仅有助于排除故障，还能大大改善用户体验。

1 编写错误信息的原则

• 描述：对问题和错误原因的清晰描述。
• 解决方法： 提供用户可以遵循的解决方案。

2. 坏榜样和好榜样

• 坏例子：输入无效。
• 好例子：您输入的值无效，请仅输入韩文姓名。

3. 令人困惑的按钮信息

• 坏按钮：是/否
• 好按钮：保存后离开/不保存就离开

第 4 章：从读者角度编写发布文档和崩溃报告

发布文件和碰撞报告是在您和公司之间建立信任的重要文件。

1. 如何创建变更日志

• 从用户角度对项目进行分类：将其分为新功能、增强功能和错误修复，或根据用户流程（开始-中间-结束）进行分组。
• 删除不必要的细节，保持简单明了。

2. 总结和归纳

• 转述摘要可提高可读性并突出关键信息。
• 例如更快地进入游戏室

3. 以故障排除为重点的报告

• 按以下顺序书写：问题、原因、解决方案和后续计划。
• 帮助读者轻松了解现状。

第 5 章：撰写包含描述、说明、论证和叙述的开发指南

开发指南应善用解释和论证，使读者易于理解。

1. 说明

• 明确描述服务的范围、目的和特点。
• 示例：AWS 中的类别："云存储服务

2. 描述

• 图文并茂地解释复杂的结构。
• 文字与图片相匹配：视觉效果和文字应相匹配，以避免混淆。

3. 论证

• 用具体的证据支持你的主张，让读者信服。
• 例如："测试当值增加到 30 时是否存在性能差异"。

第 6 章：撰写一份能为你赢得业务的 SI 建议书

您的 SI 提案是一份重要文件，代表着贵公司的竞争力。

1. 创建结构化提案

• 确定问题：明确客户的需求和问题。
• 解决方案：我们的解决方案将带来的价值以及具体的行动计划。

2. 发挥自己的优势

• 突出与竞争对手不同的优势。
• 例如："我们的服务保证 20% 更快的处理速度"。

第 7 章：轻松撰写和运营科技博客

科技博客是打造个人品牌和为社区做贡献的绝佳工具。

1. 编写技巧

• 从你的角度出发，利用你的经验和数据进行写作。
• 考虑读者的水平，但要坚持自己的原创性。

2. 操作提示

• 定期发布信息以建立信任。
• 如果能附上简单的代码片段或实验结果就更好了。

完成开发人员的书面审查

"《为开发人员写作》是一本实用的写作指南，每个开发人员都需要了解。如果你想成为一名通过写作增加价值的开发人员，而不仅仅是一名代码出色的开发人员，那么这本书是你的必读书。它将使你的开发和写作都更上一层楼！

#eveloper's Writing 出书术语表

1. 发布说明

• 定义: 发布说明是记录软件新版本发布时添加的功能、修正的错误和改进的文档。
• 目的：用于向用户和利益相关者通知软件变更。
• 组成部分：
  • 新功能：软件新增的主要功能。
  • 已修复的错误：已解决以前版本中的错误或问题。
  • 改进：改进软件，包括性能、用户界面/用户体验和稳定性。
• 例如
  • [版本 1.2.3]
  • 新功能：新增黑暗模式。
  • 改进：提高页面加载速度 20%.
  • 错误修复：已更正登录失败时正确显示的错误信息。

2 更改日志

• 定义：变更日志是记录软件变更历史的文档。可将其视为发布说明所依据的内部记录。
• 区别（与发布说明相比）：发布说明是为外部用户编写的，而变更日志是为开发人员或内部团队编写的。
• 更改日志更加详细，技术性更强。
• 用途：促进开发人员之间的交流，跟踪修订历史。

3. SI 提案

• 定义：系统集成（SI）提案是为赢得系统集成项目而创建的文件。
• 目的：分析客户问题，并提出技术和运营解决方案以解决问题。
  • 组成部分：
  • 项目概述：您的要求和目标。
  • 技术解决方案：您建议的技术和系统结构。
  • 预期成果：项目完成后的预期成果。
• 重要性：这一点非常重要，因为建议书的质量将决定您能否获得项目。

4 命名公约

• 定义：在代码中对变量、函数、类等进行系统命名的约定。
• 主要公约
  • 驼峰式符号（Camel Case）：第一个单词的第一个字母大写，随后单词的第一个字母大写。
    • 例如：totalVisitors, calculateSum.
  • 帕斯卡符号（帕斯卡大小写）：将每个单词的第一个字母大写。
    • 示例CalculateSum, TotalVisitors.
  • 蛇形符号（蛇形大小写）：用小写字母书写所有单词，单词之间用下划线 _ 分隔。
    • 例如：total_visitors（访问者总数）、calculat_sum（计算总和）。

点击评论

• 定义：注释是代码中描述特定代码目的或行为的文本。
• 类型
  • 行注释：单行注释。通常以 // 或 # 开头。
    • // 初始化用户输入。
    • 输入 = ""；
  • 块注释：多行注释。写法为 /* */ 或 """"""
    • /*
    • 该功能用于存储用户数据。
    • 存储格式：JSON
    • */
• 作用使代码更易于理解和维护。

6. 技术博客

• 定义：由开发人员撰写的博客，用于分享他们的经验、技能和诀窍。
• 目的是
  • 打造个人品牌：从技术上提高自己的知名度，扩大自己的人际网络。
  • 社区贡献：通过分享有用信息，为开发人员社区做出贡献。
• 写作提示：经验和数据要具体。包含代码片段和视觉效果，以增加可读性。

7. 方便用户的错误信息

• 定义： 帮助用户理解和解决问题的信息。
• 内容:
  • 错误描述: 明确问题所在。
  • 原因: 错误发生的原因。
  • 解决方法：为用户提供解决该错误的具体说明。
• 一个坏榜样和一个好榜样：
  • 坏例子：错误 404
  • 好例子：页面未找到，请重新检查 URL。

除了开发人员撰写的文章外，我们还为开发人员推荐了一些书籍。 开发人员书籍推荐--"软技能"，完美融合开发与生活的必读书！ 快来看看这篇文章，了解这本书的内容吧！它将通过一本由开发人员撰写的书，带你更深入地了解开发人员的世界。