告别难懂文档！用爆火的 Markdown 轻松搞定应用文档，提升团队协作效率！掌握 README.md 编写、代码块高亮等最佳实践，配合 Visual Studio Code 等编辑器，让你的项目文档清晰易懂，告别祖传代码无人维护的窘境！
译自：Best Practices for Creating Markdown Documentation for Your Apps
作者：Damon M Garn
存在各种格式化语言来管理文本在软件文档中的显示方式。其中最关键的一种是 Markdown。它提供了一种简单的语法来生成标题、强调文本、有序/无序列表等。如今，Markdown 是一种用于编写技术内容的标准工具，例如在 GitHub 或其他基于 Web 的位置上找到的项目。
Markdown 是一种轻量级标记语言，用于向纯文本文档添加格式。它由 John Gruber 于 2004 年创建，其主要目标是使人们能够使用易于阅读、易于编写的纯文本格式进行编写，该格式可以选择性地转换为结构上有效的 HTML（或 XHTML）。
本质上，Markdown 允许你使用一种简单的语法来创建格式化的文本（如标题、粗体文本、斜体、列表、链接和图像），这种语法既不显眼，即使在其原始、未渲染的形式下也保持高度可读性。
文档可以是任何开发项目的重要组成部分。它提供关键信息，包括：
- 能够实现关于应用程序的知识的转移和保存。
- 能够实现协作和故障排除。
- 确保合规性和质量。
- 能够实现可扩展性和功能增强。
Markdown 的简单性使其成为记录项目的绝佳选择。请注意，有几种不同的 Markdown 风格，每种风格都有特定的优势。你的组织标准化一种风格至关重要。
常见的 Markdown 变体包括：
- Markdown(original): 原始规范。
- CommonMark: 阐明原始规范的各个方面以提高一致性。它通常是标准口味。
- GitHub Flavored Markdown: 添加更多 Markdown 功能，包括表格、任务列表、删除线和其他组件。如果你经常发布到 GitHub，请使用此选项。
- Markdown Extra：添加新功能，包括脚注。经常与 WordPress 一起使用。
在为你的团队选择工具之前，请务必探索每种工具的功能。
将 Markdown 集成到你的文档项目中，需要的不仅仅是选择一个版本规范。在关键的第一步的基础上，建立符合你的组织、团队或项目需求的格式标准。定义一个样式指南，使所有作者都能够创建一致的文档，这样才能获得最大的成功机会。
请考虑以下在文档中使用 Markdown 的最佳实践：
规划：通过定义文档应该（和不应该）涵盖的内容来规划成功。定义职责、存储位置和 Markdown 风格。
- 定义文档所涉及的应用程序的各个方面。
- 定义谁负责编写和维护文档。
- 指定存储位置。理想情况下，文档与应用程序一起位于 GitHub 等存储库中。
- 指定所有作者应使用的受支持的 Markdown 风格。
结构和组织：使用清晰且合乎逻辑的结构来组织文档，引导读者完成必要的步骤，同时建立在概念之上。
- 使用三个或更少的标题来定义章节。
- 包括一个
README.md文件来解释文档的范围、结构和目的。
格式化：为所有文档定义并使用一致的格式。
- 项目符号列表易于扫描并提高可读性。
- 对顺序任务使用编号步骤。
- 应用日期和时间标准。
- 使用内部链接来引用文档的其他部分。
图 1：Markdown 显示在左侧，预览显示在右侧。请注意标题、链接和列表。
语法：仔细管理代码和命令示例，以确保清晰度。确定何时使用内联代码与代码块。
- 对单个命令、文件名、标志或其他代码引用使用内联代码格式。
- 对大量命令或代码段使用代码块。
- 在使用代码块时指定编程语言。
图 2：对单个命令使用内联编码格式。对较大的代码段使用代码块。
清晰度：使用简单的语言并避免使用成语。请记住，许多文档项目都会被翻译成多种语言。
- 第一次使用首字母缩略词时，请拼写出来。
- 避免使用俚语。
- 在文档文件的顶部添加元数据以总结内容。
- 依靠简短的段落和句子来保持简洁。
- 仔细检查文档中的拼写和语法错误。 不要过度使用斜体、粗体、下划线和其他强调信息的方法。
可访问性 (Accessibility)：在编写文档时，要考虑到可访问性，尤其是在 URL 和图像方面。
- 为图像使用 alt 文本，以支持屏幕阅读器。Alt 文本也有助于 SEO。
- 为 URL 和图像提供描述性文本。
图 3：描述性 alt 文本辅助屏幕阅读器和 SEO 结果。
一致性 (Consistency)：一致的格式、词汇和组织可以增强文档的实用性。
- 为所有文档作者制定一个风格指南，以供遵循。
- 使用 Markdown linting 工具来捕获错误并保持风格。
- 征求用户对如何改进文档的反馈。
维护 (Maintenance)：当应用程序版本更新时，更新文档。
- 将文档资源（时间、金钱等）纳入版本更新计划。
- 确保新章节与文档的其余部分保持一致。
- 为新章节创建新的内部链接。
持续改进 (Continual improvement)：努力持续改进文档。
- 征求并整合用户反馈。
- 确保文档组织在版本更改和功能增强方面保持逻辑性。
- 仔细审查文档，以发现不一致和错误。
- 测试所有内部和外部链接，以避免导致混淆或沮丧的断开链接。
许多应用程序，尤其是开源项目，依赖于整个社区来维护文档。风格指南、模板和明确的期望在这些协作环境中至关重要。认识到随着时间的推移，许多人将使用该文档至关重要。
找到合适的编辑器是使用 Markdown 记录项目的另一个重要部分。虽然任何基本的文本编辑器都可以工作，但能够显示预览的工具非常有用。提供 linting 或语法检查的工具也会有所帮助。
许多常见的编辑器都是可扩展的，可以与 Markdown 一起使用。请务必检查您现有的工具集，看看是否已经有熟悉的 Markdown 实用程序。
Visual Studio Code：您的程序员可能已经在使用的这个编辑器，可以很容易地修改其配置以适应 Markdown。StackEdit: 一个基于 Web 的编辑器，集成了预览和编辑窗口。它包括与云存储（如 Dropbox 和 Google Drive）的集成。Typora: 提供出色的预览功能和高级功能。ghostwriter: 一个功能丰富的编辑器，具有专注模式、各种导出功能和实时预览选项。 在标准化之前，花一些时间评估这些应用程序。
越来越多的 IT 部门依赖于基于代码的项目，从传统的开发工作到基础设施即代码。确保您的开发和管理团队生成准确、直接和最新的文档对于 IT 项目的长期成功至关重要。Markdown 是满足此要求的绝佳工具。
您会选择 Markdown，因为它具有简单而强大的格式化功能，从而大大减轻了文档应用程序的工作量。遵循上述最佳实践，以提供最佳的成功机会。