聚焦Write the Docs文档社区
浏览：0
巴克励步
Write the Docs是一个面向软件文档工作者的全球社区，汇聚了程序员、写作者、支持专家等，致力于文档的艺术与科学。它通过线上论坛、线下聚会和年度会议，为文档人提供交流平台和资源，推动文档质量的提升。
你是否知道，有一个为热爱软件文档的人们而设的繁荣社区？
Write the Docs 致力于成为“最受欢迎的互联网社区”（我们认为他们成功了！）。它专注于文档写作的艺术与科学。该组织的成员自称为文档人，他们可以是任何关心软件文档、沟通及其用户的人，无论职位或头衔如何。
尽管存在其他的技术写作社区，但 Write the Docs 汇聚了程序员、写作者、支持专家、营销人员等，独特地融合了语言天赋、技术专长以及对卓越软件体验的热情。
起源故事：汇聚文档人
不足为奇的是，由于许多组织错误地将文档视为一种奢华的附加品，文档写作者一直缺乏一个能将他们的工作聚焦起来的社区。
Troy Howard 和 Eric Holscher 在意识到没有专门服务于文档写作者的社区后，创立了 Write the Docs。这是一个偶然诞生的想法，是源于一种自然需求的副产品。
在他们家乡波特兰，已经存在一个文档写作者群体，尽管它从未如此自称。Eric 和 Troy 举办了第一次聚会，并决定将这件事扩展到线上。
他们说：
“世界上存在一个文档人部落。直到此刻之前，他们还没有一个中心化的场所来相互结识，并凝聚成一个社区。我们正在提供一个空间，让这一切得以发生，无论是在线下还是线上。”
他们建立了自己的网站，并在 Hacker News 上发布了一个链接，期望为他们的会议获得几十个注册。结果，数百人表达了他们的兴趣，从开发者到设计师，再到初创公司。
影响力：让文档世界更安全
Kelly O’Brien，Kayako 的自助服务内容经理，曾是一名行业杂志的自由记者。她维护 Drupal 网站的经验将她带入了文档世界，并且从此再未回头。
对于那些希望在文档领域建立职业生涯的人，Kelly 说：“加入 Write The Docs Slack 团队——这是一个非常棒的社区，无论你是刚刚开始从事文档工作，还是已经做了很久，它都是一个极好的资源。”
查看我们对 Kelly 的采访（在 Baklib 博客上），可以一窥文档工作者的生活。
“Write the Docs 已经成为我多年来作为一名独立技术作者时渴望加入的部落。它给了我巨大的机会去组织、会面、演讲/展示，并与许多背景各异的人交谈，然而他们都热爱内容和文档如何塑造一个产品/服务/应用。”
—— Swapnil Ogale，技术传播者，Write the Docs Australia 组织者
“我在 Rackspace 上一份工作时发现了 Write the Docs。我写过一篇博客文章，讲述了 Write the Docs 如何激励我们的团队，当时我们正在将我们的文档和文档流程转变为基于开源工具的协作模式。”
—— Margaret Eker，高级技术文档工程师
我们最喜欢的演讲精选
Write the Docs 有许多精彩的演讲，并已分享视频供大家欣赏。以下是我们挑选的一小部分关于文档工作的演讲，它们有趣、真诚且极具启发性。
1. 即时文档：运用敏捷方法论创建活的文档
演讲者： Bri Hillmer (@writebriwrite)
简介： Bri Hillmer 是 SurveyGizmo 的文档协调员。在本演讲中，她分享了2014年作为新任文档协调员面临的挑战：创建一个人们真正愿意使用的“活”的知识库，并将文档模式从“以防万一”转向“即时”。
简介： Bri Hillmer 是 SurveyGizmo 的文档协调员。在本演讲中，她分享了2014年作为新任文档协调员面临的挑战：创建一个人们真正愿意使用的“活”的知识库，并将文档模式从“以防万一”转向“即时”。
她设计了一个名为“即时文档”的工作流程，借鉴了制造业中用于高效管理库存的JIT（Just-In-Time）生产策略。通过将JIT应用于文档，团队可以创建“刚好够用、刚好及时”的文档。
演讲详细介绍了她的团队如何成功创建、完善并运行这一流程。
想了解更多关于 JIT 文档的知识？请查阅 Bri 的博客文章，她深入解释了 JIT 文档，并分享了她如何在 SurveyGizmo 成功实施 JIT的策略。
两大卓越团队的协作：弥合文档与客户支持之间的鸿沟
作者：Neal Kaplan。在 Twitter 上关注他：@NealKaplan
在这个视频中，Neal 探讨了文档工程师如何利用支持客服的知识来优化文档。反过来，他也探索了文档工程师如何能让客服的工作更轻松。文档团队与支持团队携手合作，能够为客户提供更卓越的支持体验。
用户协助（文档）是自助式客户支持的另一种说法。对于一个公司而言，要想取得成功，文档和客户支持必须在战略层面紧密协作。
简而言之，文档工程师可以与客户支持团队合作，将 RTFM（去读那该死的说明书）中的“F”变成“FANTASTIC”（太棒了）！以下是文档工程师与客户支持协作的方法：
- 手动审阅支持工单
- 设置自动化通知，提醒文档工程师创建相关内容
- 与客服人员一同复盘复杂案例和解决方案
- 尽可能多地了解您的客户
- 分析工单指标，并通过添加更多文档来追踪改进效果，观察指标如何变化
- 让支持客服也参与到文档编写中来！
借助 Baklib 这样的专业平台，可以轻松实现工单分析、内容协作与自动化通知，让文档与支持的融合更加顺畅高效。
如何为不爱阅读的人编写文档
作者：Kevin Burke。在 Twitter 上关注他：@ekrubnivek
本次演讲探讨了您文档的“可查找性”以及您所撰写页面上的实际文本。可用性研究人员数十年来已经认识到，用户在线阅读的方式与纸质阅读不同。他们不会逐字阅读，而是快速浏览页面以寻找所需内容。在本演讲中，您可以深入了解用户如何找到问题答案。
如果用户无法轻松理解您的文档，他们会迅速放弃，从而导致收入损失。他们也可能对产品功能一无所知，这同样是收入损失。他们几乎肯定会向您的团队提出不必要的支持问题，这又会给您的公司带来更多成本。
这对文档工作者提出了巨大挑战，也是这份工作如此令人兴奋的原因之一。解决方案是专注于文档的可用性，确保用户吸收他们所需的信息。
本演讲探讨了关于用户如何吸收网络信息的可用性研究、您的文档可能让忙碌用户感到挫败的方面，以及Kevin在Twilio进行用户测试时获得的经验教训。
屏幕录制入门
演讲者：Diana Potter。在Twitter上关注Diana：@drpotter
在本演讲中，您将了解不同的学习风格类型，以及这如何影响您创建文档的方式。
文档工作者可能难以承认，并非每个人都愿意阅读他们精心撰写的文档。虽然人们有时会阅读，但并非每个人都通过阅读文档来获得最佳学习效果。有些人主要是听觉型或视觉型学习者。
Diana的目标是确保她的文档能吸引尽可能多的学习风格。这意味着她需要拓展文档工作者的技能边界，从单纯撰写文档延伸到录制文档。她一直在学习如何创建屏幕录制视频，现在正与大家分享这些知识。
借助像 Baklib 这样强大的“AI+内容”平台，您可以轻松地将文本、图像、视频等多种格式内容整合到统一的知识库中。Baklib 不仅能帮助您创建结构清晰、易于查找的文档，其内置的富媒体支持功能更可让您无缝嵌入屏幕录制视频、教程等视觉化内容，从而有效覆盖不同学习风格的受众，无论是构建产品文档、在线帮助中心还是内部知识库，都能显著提升信息传递的效率和用户体验。
Diana 详细讲解了如何选择合适主题、拟定大纲、撰写脚本以及录制音频和视频。制作屏幕录像并不需要你是专业的配音演员或摄像师。即使是一位普通的写作者，也能创造出精彩的内容。
要么吸引，要么消亡：打造不可或缺文档的四大技巧
作者 Kelly O’Brien。在 Twitter 上关注她：@OBrienEditorial
Kelly 探讨了如何让你的技术写作更能吸引读者。她分享了四个技巧，这些技巧源于她之前担任杂志撰稿人时用来吸引并保持读者注意力的经验。
在撰写文档时，你需要赢得客户的信任，这样当他们遇到软件问题时，才会倾向于查阅你的文档。这需要了解你的客户是谁，以及如何优先考虑他们的需求。要对他们的困扰表示理解。
文档的四大“致命伤”是：
- 冷漠之殇
- 疏离之殇
- 不耐之殇
- 迷失之殇
Kelly 讲述了如何在你的文档中战胜这些致命问题。
如何参与 Write the Docs 社区？
渠道 描述
| Slack | 与社区建立联系最快的方式是加入他们非常活跃的 Slack 频道。
| 新闻通讯 | 订阅月度新闻通讯并查看存档，获取来自社区的有趣信息。
| 播客 | 收听全新的播客讨论和聚会录音。 Write the Docs 资源与活动指南
| Slack | 与社区建立联系最快的方式是加入他们非常活跃的 Slack 频道。
| 新闻通讯 | 订阅月度新闻通讯并查看存档，获取来自社区的有趣信息。
| 播客 | 收听全新的播客讨论和聚会录音。 Write the Docs 资源与活动指南
参与文档社区 Write the Docs
Write the Docs 是一个面向所有关心文档的人士的全球社区。以下是为文档工作者提供的丰富资源和参与方式。
在线资源与活动
- Twitter: 在 Twitter 上关注话题标签 #writethedocs，并 关注官方账户，参与以文档为核心的讨论。
- 会议视频: 每年的会议演讲都会被录制并分享。请浏览他们在 YouTube 上的 精彩视频集锦。
- 文档指南: 查看 官方文档指南，该指南旨在为新手和专业作者提供构建、组织和编写软件文档的最佳实践手册。
- 线下聚会: Write the Docs 在全球各地定期举办线下聚会。查看他们的 聚会活动页面，了解北美、伦敦、巴塞罗那、澳大利亚和首尔等地的活动。如果你所在的地区没有聚会，欢迎发起一个！
- 大会: 参加大会是深入了解行业趋势、与同行交流的绝佳方式。这里是 当前及过往大会的完整列表。
系统优化与故障排查指南
本指南旨在提供一套清晰、可操作的步骤，帮助您优化系统性能并解决常见问题。请按照以下章节顺序进行操作。
1. 系统检查与更新
在进行任何优化之前，请确保您的系统处于最新且稳定的状态。
- 更新系统：运行系统更新命令，确保所有软件包为最新版本。
- 检查磁盘空间：使用 df -h 命令查看磁盘使用情况，清理不必要的文件。
- 查看系统负载：使用 top 或 htop 命令检查 CPU 和内存使用率。
提示：定期更新系统是保持安全和性能的基础。建议设置自动更新或每周手动检查一次。
2. 网络连接诊断
网络问题是导致应用缓慢的常见原因。请按顺序检查以下环节：
- 测试本地连接：使用 ping 127.0.0.1 检查本地网络栈。
- 测试网关连接：使用 ping <你的网关IP> 检查内网连通性。
- 测试外网连接：使用 ping 8.8.8.8 检查 DNS 和外部网络。
- 检查DNS解析：使用 nslookup 或 dig 测试域名解析是否正常。
如果上述任何一步失败，请检查您的网络配置或联系网络管理员。
3. 服务状态与管理
关键后台服务的状态直接影响系统功能。请确保所需服务正在运行。
服务名称 检查命令 管理命令 说明
| 网络服务 | systemctl status network | systemctl restart network | 管理网络连接
| Web 服务器 | systemctl status nginx | systemctl reload nginx | 重启或重载配置
| 数据库 | systemctl status mysql | systemctl restart mysql | 重启数据库服务
| 网络服务 | systemctl status network | systemctl restart network | 管理网络连接
| Web 服务器 | systemctl status nginx | systemctl reload nginx | 重启或重载配置
| 数据库 | systemctl status mysql | systemctl restart mysql | 重启数据库服务
4. 日志分析与故障定位
系统日志是排查问题的宝贵资源。重点关注以下日志文件：
- 系统日志：/var/log/messages 或 /var/log/syslog
- 认证日志：/var/log/auth.log 或 /var/log/secure
- 应用日志：检查您的特定应用程序日志目录。
使用 tail -f /var/log/your-log-file 可以实时监控日志输出。
高效的故障排查源于对日志的仔细阅读。错误信息中的关键字通常是解决问题的关键线索。
5. 性能优化建议
5.1 内存优化
如果系统内存不足，可以考虑：
- 增加交换空间（Swap）。
- 终止不必要的进程。
- 优化应用程序的内存配置。
5.2 I/O 优化
磁盘 I/O 瓶颈可能导致系统卡顿：
- 使用 iotop 命令查找高磁盘读写进程。
- 考虑使用更快的存储设备（如 SSD）。
- 对数据库等 I/O 密集型应用进行调优。
6. 安全加固（可选但推荐）
在保证性能的同时，安全不容忽视。
- 更新所有密码为强密码。
- 配置防火墙（如 firewalld 或 iptables），仅开放必要的端口。
- 定期审查用户账户和权限。
- 考虑安装 Fail2ban 等工具防止暴力破解。
7. 获取更多帮助
如果您在执行上述步骤后问题依然存在，可以尝试以下途径：
- 查阅相关软件的官方文档。
- 在技术社区（如 Stack Overflow、Server Fault）搜索错误信息。
- 联系您的系统提供商或 IT 支持团队。
希望这份指南能帮助您有效管理和优化您的系统！
