(helpjuice.com)https://helpjuice.com/blog/software-documentation
原文地址
软件文档是工作软件的重要组成部分。
无论是 API 文档、发布说明还是面向客户的帮助内容，在运送新产品时，您都无法跳过文档。
"文档是软件项目中最重要的部分之一。然而，许多项目几乎没有或根本没有文档来帮助其（潜在）用户使用该软件，"撰写文档的联合创始人埃里克·霍尔舍尔说。
幸运的是，有许多软件品牌在文档方面处于领先地位，我们将在这篇文章中查看一些文档最佳实践。
查看其他软件文档示例可以激发您自己的项目，您的流程将完全属于您自己的项目。
软件文档类型
首先，有几种类型的软件文档，但两个主要类别是产品文档和系统文档。
每个文档类型都需要稍微不同的方法，因为它们针对的是不同的受众。
用户文档
来自 Divio 的Daniel Procida谈到了四种不同类型的软件用户文档（请记住，用户也可以是开发人员）：
- 如何指导-面向问题，通过一系列步骤来实现用户的真实目标
- 教程-以学习为导向，通过一系列步骤来学习用户的概念
- 参考文档–面向信息、技术描述的软件（可能包括软件设计文档）
- 解释–以理解为导向，为用户澄清或阐明特定主题
仅供开发人员使用
您的用户也可以是开发人员，并且只有针对开发人员的非常特定类型的文档。这是它变得迷人的地方，但一些开发人员专用文档包括：
- API文档–有关拨打API呼叫和课程的参考文档
- 发布说明–描述最新软件或功能版本的信息，以及错误修复
- README–软件的高层概述，通常与源代码一起
- 系统文档–描述软件系统的文件，包括技术设计文档、软件要求和 UML 图表
考虑与软件并存的代码文档，可能位于 GitHub 或类似工具中-否则，您的开发人员都不会阅读它。
区分内部软件文档和面向外部最终用户的文档-您通常需要不同的编写器。
我们将主要关注本指南中的最终用户面向文档。
遵循预写练习
您也可以考虑编写文档作为编写代码的"预写"练习的一部分 - 当您有多个开发人员处理同一功能时，这尤其有用。
正如亚马逊高级软件开发人员James Hood所说："随着功能的大小和复杂性的增长，所需的预写量也会增加，尤其是当多个开发人员将就一项功能进行协作时。
您不是在编写代码本身，而是在编写要用于解决特定问题的代码。
这就像在实际实施任何代码之前，集思广益，讨论您将要在软件中使用的解决方案。
确定目标受众
如果您的目标受众不是内部受众，那么您的受众很可能就是您的客户群。
但是，您仍可能进一步细分您的客户群。
Splunk 在他们的书《产品是如何为技术作家定义受众的文档》中提供了深入的指南。
以下是 Splunk 的一段话："可靠且易于访问的文档需要全面的产品知识。它也同样适用于了解您的受众，如果不是更多的话。
这是一个不仅对技术编写者有用的练习，而且对公司的其他成员，包括营销、工程、产品和支持也很有用。
- 定义您的用户。您可以从可用的用户信息开始，并与面向客户的团队（如支持）交谈。
- 确定用户的目标（例如，安装数据库）。
- 创建受众角色。
- 创建受众定义（例如入门级管理员受众）。
- 为产品创建使用案例（例如，在 CRM 系统中管理企业客户）。
- 为用户（例如常见问题解答、维基或知识库）识别正确的交付格式。
- 创建适当的范围和在正确的细节水平的内容。
- 确定合适的用户，以提供有关文档的反馈。
- 开展用户研究并与用户沟通。
请记住，您的软件用户可能会随着时间的推移而改变。每年至少重复一次此练习。
遵循敏捷文档实践
软件技术编写者在敏捷而不是瀑布中工作越来越普遍——71%的公司将敏捷软件文档方法用于其软件项目。
敏捷宣言的定义是：
- 流程和工具的个人和互动
- 全面文档的工作软件
- 客户在合同谈判方面的协作
- 响应计划后的变化
文档（如代码）方法是敏捷的子集，它意味着为文档使用与软件相同的工具和流程。
您的目标是尽可能少的文档数量。你可以在安妮·温柔的书《像代码一样的文档》中了解更多。安妮说：
"GitHub 和类似的代码系统避免了文档贫民区，因为编写人员使用的工具与开发人员使用的工具相同。通过采用软件技术，如持续集成、自动测试和文档的增量改进，您可以获得与代码本身相当的文档。
使您的技术编写人员成为每个 Scrum 团队的一部分，而不是拥有专门的文档团队，因为这鼓励了编写人员和开发人员之间的更好协作。
在生成文档时，您需要考虑版本控制、源控制和协作。
将文档任务保留在与软件相同的工具中，例如Jira。
与其拥有自己的内容管理系统，不如使用开发人员用于代码的相同版本控制软件。
实时文档
《及时》文档是敏捷方法的子集，源自丰田生产系统。
您没有全面记录每个功能，而是根据客户支持票证生成必要的文章。
当然，这种方法主要与面向客户的产品文档有关，而不是针对技术人员的系统文档或 API 文档。面向开发的文档，您希望尝试全面。
最低可行文档是一种在访问技术编写资源有限且必须快速生成相对大量的文档时有意义的方法。
这意味着你的目标是获得成功所需的最少数量的内容，而不再如此。
敏捷为大家说："我们当然不需要"以防万一"文档，但我也相信，认为敏捷团队可以有效地与零文档是一个谬论。
我们只需要足够的文档，以确保团队取得成功。
在开发过程中优先考虑文档
除非您齐心协力通过软件开发生命周期确定优先级，否则软件文档很容易落入雷达之下，直到最后一刻。
除非附带相应的文档，否则不允许开发人员发货。
雇佣技术撰稿人，可以提升您公司内文档的价值——Splunk对如何做到这一点有一些很好的建议。
使用与开发团队相同的工具确实可以帮助解决此问题，因为您的文档更加明显。
例如，斯普伦克说："那么，是什么让技术作家与众不同呢？足智多谋和渴望是关键。当您筛选技术作家候选人时，寻找真正的发现欲望。从根本上说，工作不是写作或学习技术。这是一个关系业务，更像是调查性新闻比什么都重要。
我们将在以后的部分中涵盖聘用技术编写人员的重要性。
文档或它没有发生是写文档社区精神的一部分 - 本质上意味着没有相关文档，任何软件或功能都是不完整的。
这意味着授权您的开发团队中的每个人都成为文档员，从工程到产品，到支持，尽管不是每个人都不会直接编写文档。
制定内容策略
文档本身不会显示。特别是当你有一个复杂的产品，经常改变，你需要采取有意识的方法，你如何生产文档。
您的内容策略在确定您采取的方法时会根据受众的定义进行。
即使您使用"及时"方法，您也必须考虑您的文档作为一个整体。
例如，对您的文档进行全面审核-许多公司在多个地方都有相同的内容，大量过时的文件，或完全错误的内容。
文档内容策略可帮助您保持正轨、分配资源和管理时间。它将帮助您将文档与版本一起时间，以便您可以了解即将发布的的内容。
它可以对工程团队特别有帮助，因为这篇文章按增量探索。
根据增量，"根据受众需求绘制地图的内容可以更好地理解，减少困惑和挫折感：它提供了有用的信息，解释了混乱的任务和概念，并预测了它们的挑战可能发生在哪里。
与主题专家密切合作
在软件文档中，没有人拥有所有的答案，您的技术编写者将评估他们获得主题专家最多信息的能力。
正如斯普伦克所说："你与主题专家的关系对于你的成功至关重要。这些中小企业中有许多将是工程师。
斯普伦克建议：
- 了解工程工作流程
- 学习工程师的语言，以便您可以用它来与他们交谈
- 在遇到任何工程师之前在软件上做作业
- 熟悉产品的术语
您的开发人员可能非常了解该产品，因此可能很难从他们那里得到可以转化为文档的实际答案。
文档不仅应由技术编写人员编写，最好是文档团队、工程师和支持之间的同步协作。
您需要腾出时间进行技术审查，以便您的中小企业能够验证文档的准确性，以及在用户身上测试您的文档。
问题卡和测试
当我们谈到使用敏捷方法时，我们已经对您的文档的质量保证 （QA）进行了一点讨论。
文档在经过技术验证之前不应发布，这是 QA 测试文档以查看您提交的任何解决方案是否有效的点。
您的客户不应是文档的第一批测试人员，或者您未能提供工作文档。
将此测试阶段构建到敏捷流程中，以便团队成员在产品或功能船舶之前留有时间进行测试。
您还需要包括一个阶段，其中产品或工程团队的相关成员审查您的文档，以检查技术准确性，所以这是团队之间的牢固关系派上用场的地方。
确保您的流程正式化，以确保所有团队成员都认识到文档的重要性。
在文档获得批准之前，不允许代码合并。
客户反馈循环
关闭客户反馈循环是敏捷流程的所有部分。敏捷开发应该是开发团队和客户之间在流程的各个阶段之间的持续沟通。
从与研究组的测试版测试，到第一次发布的反馈，以及来自客户的持续反馈，您需要保持手指在脉搏上。它并不总是一个正式的研究小组。
收集反馈的方法有很多种：
- 知识库联系表
- 启用文档注释
- 允许用户"评价"内容的有用性
- 检查您的知识库数据分析
- 客户支持票证
- 社交媒体
关闭反馈循环意味着将反馈与正确的内部部门连接起来。
如果客户支持软件出现问题，则需要将此问题传递给工程团队并记录为错误或功能请求。
如果产品营销方式存在问题，则需要将此信息传递给营销团队。
你明白了！
创建样式指南
你绝对需要一个软件文档的风格指南，就像你对你的营销活动一样。您在风格指南中应涵盖的主要内容是：
- 标准化术语（如何指您的公司和软件）
- 语音和音调
- 页面格式（使用标题、段落、列表）
- 单词选择指南（应该是互联网还是互联网——显然是前者！
- 使用视觉效果和视频
有关语法选择的建议，如是否使用牛津逗号，您可以查看标准风格指南，如芝加哥风格手册。
采用连贯的写作风格，特别是如果您使用的是作家团队，他们都以不同的风格写作。所有这些都增加了文档的用户体验，我们稍后将讨论这些体验。
软件文档模板可以派上用场，因此您的作者不必每次都咨询样式指南。
你可以自己制作，在线搜索，或者在阿特拉斯汇流等企业内容工具中找到它们。
(源)
考虑用户体验
您需要考虑文档的用户体验 （UX），尤其是面向客户的帮助内容。
仅仅写内容是一半的战斗——当客户遇到您的知识库时，他们有何感想？他们能轻易地找到他们需要的东西吗？
如果您投资于适当的知识库软件（如 Helpjuice），您将拥有专为文档用户设计的 UX 内置模板。
信息架构
您的知识库 （IA） 的信息架构遵循与任何其他 IA 项目相同的原则，是用户体验的一个方面。
这是专业技术写作帮助非常重要的地方，我们将在稍后的部分中对此进行报道。
信息架构指：
- 共享信息环境的结构设计。
- 网站和内联网中的组织、标签、搜索和导航系统的组合。
- 塑造信息产品和经验的艺术和科学，以支持可用性和无能。
- 新兴的学科和实践社区专注于将设计和建筑原则引入数字景观
查看此API文档门户从松弛：
包容性和可访问性
当您到达文档中的某个点时，您需要认真考虑具有不同需求的人如何能够使用您的文档。
例如，在实际编写内容时，考虑您的用户是否来自国际受众。您希望避免使用成语和引用，他们可能无法理解。
辅助功能与文档工具本身的用户体验有关。例如，考虑使用屏幕读取器的人是否可以访问它，屏幕阅读器会大声向使用屏幕阅读器的人朗读测试。
覆盖文本的图像不可访问，因此请考虑您的屏幕截图，并确保它们具有附带的文本。
考虑知识库设计的对比颜色，以及如何设计链接，以确保其他有视觉障碍的用户能够成功参与您的网站。举一个例子，从写文档的网站：
网站设计非常清晰，易于使用，带有下划线链接和短段落。黑白配色方案为视障用户提供了高对比度。
内容可发现性
首先考虑客户如何到达您的知识库。很少有客户会考虑您的知识库作为一个整体，几乎没有人会到达您精心构建的主页。
考虑每一页都是马克·贝克描述的"第一页"原则。根据EPPO，人们"觅食"的信息，如动物寻找食物，而不是学习线性的方式，你会与一本书。
没有"开始：从开始。
马克说："没有"从这里开始"页面的网络。无论你把脚趾伸进网上，那都是你的第一页。我们不能避免这种情况。无论您是读者还是作家，无论您喜欢与否，Web 都是这样工作的。每一页都是第一页。
如果没有人能找到，您的软件文档是不好的，但有很多方法可以推广您的内容。事实上，谷歌的搜索引擎往往是许多用户的"第一页"。
您的知识库软件应该通过搜索引擎索引，并带有所有正确的元标记。您还应从软件应用程序链接到文档，因为这是用户自然会陷入困境的地方。
如果可能，请利用客户需要时提供的环境帮助。
例如，如果客户在计费时遇到问题，请确保链接将他们带到带有计费文档的页面，以帮助解决他们的问题。
以下是 Slack 内部上下文帮助的示例：
选择合适的软件
要将文档交付给用户，您需要适当的软件。使用 GitHub 和静态站点生成器可能没问题，或者您可能需要具有更好用户体验的工具。
知识基础软件（如 Helpjuice）使您能够轻松地在优化搜索和发现的时尚网站中创建和发布文档。
查看财富吧帮助司法知识库的这个示例：
版本控制
当您对产品或功能的版本进行重复时，您需要跟踪文档的不同版本。
这甚至可能意味着创建全新的知识库，并为不同版本的产品维护多个 KB。
Helpjuice 允许您创建不同版本的文档，甚至在编辑器中在它们之间切换。
许多公司需要同时为使用不同版本的客户保留不同版本的文档。
在协作工具（如阿萨纳或特雷洛）中跟踪您的文档任务也至关重要。无论您的工具是什么，请确保每个人都在使用它以达到最高生产率。
轻量级标记语言
考虑您是否想用轻量级的加价语言工作。如果您正在处理代码等文档，并且希望将内容与代码库一起保留，则这尤其有用。
GitHub 等工具允许您在 Markdown 中工作，通常您的技术编写人员必须能够使用加价。
在加价语言方面有几个不同的选项：
- 标记
- 重新结构文本
- 阿西多克
在轻量级加价语言中工作的好处之一是内容可以轻松地以视觉上吸引人的方式进行设计和呈现。
此外，如果您需要将内容迁移到不同的系统，如果内容是以加价方式编写的，则可以保留内容中的所有格式。
以下是文本编辑器 Atom 中的标记预览：
(源)
聘请专业技术作家
如有必要，您的开发人员编写文档没有错，但在某些时候，这不是他们时间的最佳使用。
这是专业技术作家进来的地方。您可以将技术写作外包给代理机构，也可以聘请内部专业知识。
有一件事你不能忽视的是专业技术写作技能的重要性。
如果你想通过用户体验、信息架构和对受众的理解来取得成功，那么专业的技术写作体验至关重要。
您的文档给客户留下了重要的印象，即您关心他们的软件成功，并且您在遇到问题时提供了帮助。
不专业的文件也会让潜在客户感到不安。
持续改进
文档要持续更新，您必须始终重复您的努力。留出时间来查看文档、识别丢失文档或改进经常使用的文档。
这与客户反馈循环有关。快速对客户的评论采取行动，告知您的文档未能解决问题。
抽出时间与支持代理讨论他们可能发现哪些文档有用，甚至授权他们自行创建文档！
最后发言
这已经有很多要接受的！在开发软件并开始达到用户成功的新高度时，请随时参考本指南。
良好的文档实践与代码一样是软件的重要组成部分。将文档构建到您的开发过程中，并尝试使用相同的敏捷方法。
这篇文章是一个广泛的概述，还有很多要学习。在文档方面，我们只涉及许多重要主题，因此请继续研究，以更深入地发展您的知识。
正如斯普伦克所说："如果产品是文档，文档是产品，那么您也是设计师、开发人员和产品经理。