开始使用文档

撰写清晰且有效的文档对于任何项目都是至关重要的。当你创建其他人将阅读和使用的内容时， 正确的格式 起决定性作用。 良好的文档 帮助用户快速高效地理解复杂的概念。

文档是一封你写给未来自己的情书。今天的清晰写作可以节省明天无数小时的困惑。

优秀文档的基础始于 了解你的观众 以及他们的需求。作者应专注于清晰、一致，并提供读者可以遵循的实用示例。

内联 HTML 元素

HTML 定义了大量可用的内联标签，其完整列表可以在以下位置找到 Mozilla 开发者网络.

• 加粗文本，使用 <strong>.
• 将文本斜体化，使用 <em>.
• 突出显示，使用 <mark>.
• 缩写，例如 HTML 应该使用 <abbr>，可选的 title 完整短语的属性。
• 引用，例如 —— 马克·奥托，应该使用 <cite>.
• 已删除 文本应使用 <del> 和 插入的 文本应使用 <ins>.
• 上标 ^文本 使用 <sup> 和下标 _文本 使用 <sub>.

这些元素中的大多数都是由浏览器进行样式设置的，我们只做了很少的修改。

标题

有效的文档编写需要对结构和流程进行仔细关注。在组织内容时，请考虑读者如何浏览你的材料以及他们首先需要哪些信息。清晰的标题有助于用户快速浏览并找到相关部分。

代码

内联代码可与之使用 <code> 元素。通过 Rouge 支持多行代码片段。较长的行在需要时会自动水平滚动。你也可以使用代码围栏（三个反引号）来渲染代码。

// Example can be run directly in your JavaScript console
// Create a function that takes two arguments and returns the sum of those arguments
var adder = new Function("a", "b", "return a + b");
// Call the function
adder(2, 6);
// > 8

代码示例应当实用，并且与所讲解的概念直接相关。在将代码片段包含在文档中之前，务必先测试它们以确保能按预期工作。

列表

在以列表形式呈现信息时，考虑顺序是否重要。对于有顺序的步骤使用编号列表，对于不需要特定顺序的相关项目使用项目符号列表。

• 编写清晰、简明的列表项，每个列表项只关注一个概念。
• 在列表中的所有项目中使用平行结构。
• 尽量保持列表项的长度大致相同。

格式的一致性有助于读者更高效地处理信息。

1. 首先提供最重要的信息。
2. 在深入技术细节之前提供背景信息。
3. 包括读者可以立即应用的实际例子。

结构良好的内容使具有不同专业水平的读者更容易理解复杂的主题。

• 为将来参考记录你的流程和决策。
  • 包括你所做的重要选择背后的理由。
  • 请注意你考虑过的任何替代方法。
  • 在实施过程中记录经验教训。
• 随着项目的发展，定期更新文档。
• 与实际用户测试文档以识别差距。

定期维护可确保你的文档随着时间的推移保持准确和有用。

超文本标记语言 (HTML)

用于描述和定义网页内容的语言

层叠样式表（CSS）

用于描述网页内容的外观

JavaScript（JS）

用于构建高级网站和应用程序的编程语言

技术定义应该清晰并且易于目标受众理解。当更简单的术语能够有效传达相同含义时，应避免使用行话。

图像

视觉元素通过提供抽象概念的具体例子来增强理解。选择直接支持你书面内容的图片，而不是仅作为装饰使用。

桌子

表格最适合用于比较相关的数据点或呈现受益于网格布局的结构化信息。

保持表格标题具有描述性，并在排列列时考虑阅读顺序。简单的表格比复杂的表格更容易理解和维护。