使用 DocProject 和 Sandcastle 编写文档
4.91/5 (16投票s)
DocProject 的一些功能以及 MAML（用于编写概念性文档的标记语言）的用途。
引言
为 .NET 项目（但不限于）编写概念性文档和 API 参考文档可以使用多种工具完成，包括 DocProject 和 Sandcastle Help File Builder（或简称 SHFB）。在本文中，我将探讨 DocProject 的一些功能以及 MAML（用于编写概念性文档的标记语言）的用途。本文的第一部分重点介绍 DocProject，展示如何设置项目，第二部分介绍 MAML 以及如何编写概念性文档。本文并非 DocProject 构建帮助项目的完整教程，而是一个关于最重要方面的概述。
文档类型
在本文中，我将提到两种文档类型：概念性文档和 API 参考文档。在继续之前，我将先解释它们的含义。
概念性文档包括自定义主题、演练、常见问题解答、术语表、故障排除等，并使用 MAML 编写。您必须显式编写此文档（使用文本编辑器，从记事本到 Visual Studio 都可以）。
API 参考文档是对 API（命名空间、类型、方法、属性、字段、事件等）的文档，无论是托管的还是非托管的，它们都从 API 的反射信息以及代码中 XML 注释生成的 XML 文档文件生成。Sandcastle 能够反射托管 API，但需要外部工具来处理非托管 API。此文档是自动生成的，尽管您仍然需要手动编写代码中的 XML 注释。
MAML
概念性文档使用 MAML 编写的 XML 文件。MAML，有时也称为 Microsoft AML，代表 Microsoft Assistance Markup Language，是一种由 Microsoft 用户协助平台团队开发的基于 XML 的标记语言，用于编写帮助系统。该语言随 Windows Vista 的发布而引入。
MAML 的编写模型侧重于信息结构而非表示，表示稍后根据格式和样式确定。当显示一个主题时，会发生几种转换：
- 结构性：确定文档的实际结构及其文本（在此步骤中解析可重用片段和结构性条件）。
- 表示性：将文档转换为可用格式之一（包括 RTF、XAML 和 DHTML）。
- 渲染：应用样式将文档发布为所需形式。
MAML 定义了几种内容类型，包括概念性、FAQ、术语表、过程、参考、可重用内容、任务、故障排除和教程。我们将在文章后面介绍其中的一些类型。
工具链
HTML Help Workshop
这是一个用于构建 Microsoft HTML Help（或 Help 1.x）的编译器。HTML Help 是 Windows 的标准帮助系统。它随 Windows 98 推出，至今仍受支持。帮助以 .chm 扩展名的二进制文件形式提供，包含一组 HTML 文件、目录和索引。该编译器是免费的，可在此 处 下载。有关 HTML Help（当前为 1.4 版）的更多信息，请参阅 MSDN。
Visual Studio SDK
2001 年，Microsoft 引入了一种新的帮助格式，称为 Help 2.x。它旨在构建 Visual Studio .NET 2002 和 MSDN Library 的帮助系统，但后来也用于其他产品（不只是 Microsoft 的产品）。Help 2.x 文件扩展名为 .HxS，由一组 HTML 页面和几个其他文件构建（一个 .HxC 主项目文件、一个 .HxF 包含文件、一个 .HxT 目录、一个 .HxA 属性定义文件以及若干 .HxK 索引）。构建 Help 2.x 需要 Visual Studio SDK 中提供的编译器。对于 Visual Studio 2008，SDK 可在此 处 下载。
Sandcastle
Sandcastle 是 Microsoft 创建的一个帮助编译器，可在 sandcastle.codeplex.com 上免费获取。它是一个用于生成 MSDN 风格文档的工具，这些文档包含 API 参考文档（来自 .NET 程序集及其相关的 XML 文档文件）和概念性文档（来自您使用 MAML 编写的 XML 文件）。Sandcastle 生成基于 XML 的 HTML 文件，这些文件随后由上述编译器编译为 Help 1.x 或 2.x。它提供脚本来自动化此构建过程，包括使用外部编译器。但是，Sandcastle 是一个命令行工具，这使得它在使用上有些繁琐。有关 Sandcastle 的更多信息，请参阅 Sandcastle Help。
DocProject
DocProject 也是一个免费工具，可在 docproject.codeplex.com 上获取，它构建在 Sandcastle 之上，能够从 Visual Studio 自定义 Sandcastle 的输出并使用 MSBuild。它提供各种项目模板来构建已编译的帮助 1.x 或 2.x。有关 DocProject 的更多信息，请参阅 DocProject Documentation。
本文要求
本教程假设您拥有以下工具：
- Visual Studio 2008
- Sandcastle（版本 2.4.10520，来自 2008 年 5 月）
- DocProject（版本 1.11.0 RC，最终版本）
- HTML Help Workshop 编译器，用于构建 Help 1.x（*.chm）
- （可选）Microsoft Help 2.x API，用于构建 Help 2.x（*.HxS）；随 Visual Studio 2008 SDK 提供
使用 DocProject 创建项目
在本文中，我将展示如何创建一个 DocProject 项目并设置构建帮助文件的基础。我们将创建一个包含两个项目的解决方案：一个虚拟 C# 类库项目，其中包含一些用于 API 参考文档的类型，以及一个 DocProject 项目，我们可以在其中编写概念性文档并将所有内容构建到最终的帮助文件中。
安装 DocProject 后，它会将新的项目模板添加到 Visual Studio（适用于 VC# 和 VB.NET）。在本教程中，我将使用 DocProject 模板与 Visual C#。
选择类型、名称和位置后，一个向导会引导您完成为新项目选择附加设置，包括生成引擎、表示样式、帮助格式（1.x 或 2.x）以及 Sandcastle 应从中构建文档的源（来自外部源或其他项目）。这些必须是具有面向公共接口的 XML 文档的 .NET 项目。下图显示了向导的页面。
步骤 1：选择生成引擎 |
步骤 2：选择表示样式 |
 |
 |
步骤 3：导入主题和设置 |
步骤 4：选择要生成的帮助格式（Help 1.x 或 2.x） |
 |
 |
步骤 5：创建共享内容 |
步骤 6：选择内容源 |
 |
 |
这些设置都不是一次性的。它们可以在以后任何阶段进行更改。通过我的设置，我已选择使用 Sandcastle 引擎，使用 Visual Studio 2005 表示样式构建 Help 1.x，并使用我的虚拟 C# 类库作为 API 参考文档的源。（在创建项目并截取这些屏幕截图时，我只有 HTML Help Workshop，因此无法选择 Help 2.x。）
该向导会生成所有必要的文件，包括样式、脚本、图像，甚至允许挂接到项目构建过程的 C#/VB.NET 代码。这是包含虚拟 C# 类库和 DocProject 项目的解决方案的屏幕截图。
此时（假设 C# 类库的所有公共实体都带有 XML 注释），您可以实际构建项目。根据向导的配置，它应该会生成 Help 1.x（*.chm）和/或 Help 2.x（*.HxS）文件。
在第一次构建结束时，它会询问是否将输出文件添加到项目。我建议选择“否”，稍后我将回到这一点。
您在此对话框中选择的选项可以随时从 DocProject 属性窗口中更改，如下所示。可以通过 DocProject 项目的上下文菜单打开此窗口。在此处显示的所有设置在创建项目时都设置为 False（因此上述对话框会在第一次构建结束时显示）。
DocProject - Sandcastle 工具栏允许您打开 Help 1.x (.chm) 和 Help 2.x (.HxS) 帮助文件（如果它们存在）。工具栏还包含打开 Topics Designer 和 Topics Explorer 的命令。
生成的 Help 1.x 文件如下所示。
组织项目
此时，项目中没有任何概念性文档。Topic Explorer 只显示自动生成的 API 参考文档，位于一个名为 Namespaces 的节点下。
您可以使用“插入新的概念性主题”来添加一个新主题。对于每个主题，会生成两个 XML 文件，一个文件扩展名为 *.aml，另一个为 *.cmp。*.aml 文件包含文档本身，而伴随的 *.cmp 文件包含元数据，例如标题或目录下的标题。每个主题都由由 GUID 表示的唯一 ID 标识。
当您添加第一个概念性主题时，将在 Settings 文件夹下生成一个新文件。此文件名为 **topics.xml**，定义了主题的层次结构，该层次结构在 Topics Explorer 中建模。
这是 *topics.xml* 文件的内容。
<?xml version="1.0" encoding="utf-8"?>
<topics>
<topic id="679431bf-4adc-4f8b-a90d-012a4f14d6c4" file="Conceptual.aml" />
<stoc project="Project" />
</topics>
设置好所有这些之后，我们就可以开始添加更多主题并将它们组织成所需的层次结构了。
DocProject 的技巧和窍门
MAML 的 IntelliSense
概念性主题可以使用 Visual Studio 来编写，Visual Studio 可以根据 MAML 架构提供 IntelliSense。Sandcastle 会将这些架构提供到您的计算机上，DocProjects 会将它们从 Sandcastle 安装复制到您项目的 Help\Schema 文件夹。Visual Studio 可以使用项目中的这些架构来提供 IntelliSense。但是，命名空间会与它自己的架构冲突。
问题的详细信息和解决方法已在此 教程 中提供。我发现以下解决方案最受欢迎，但您可以选择最适合您的一个。
- 从 DocProject 项目中删除 **Help\Schemas** 文件夹。
- 在 Visual Studio 的全局架构缓存文件夹（位于 **[VS Install Path]\Xml\Schemas**）下创建一个目录。我们称之为 mamlcatalog.xml。其内容应如下所示：
<SchemaCatalog xmlns="http://schemas.microsoft.com/xsd/catalog">
<Association extension="aml" schema="%DXROOT%Schemas\Authoring\developer.xsd" />
</SchemaCatalog>
DXROOT 是一个环境变量，指向 Sandcastle 的安装文件夹（例如，*C:\Program Files (x86)\Sandcastle\*）。
此解决方案基本上使 Visual Studio 能够直接使用 Sandcastle 中的架构，而无需复制它们并修改其他 Visual Studio 文件。但是，您必须从创建的每个 DocProject 项目中删除 Help\Schema 文件夹。
之前（无 IntelliSense） |
之后（支持 IntelliSense） |
|
|
将输出添加到项目
我之前提到过 DocProject 允许您将构建的输出添加到项目中。我建议将其设置为“否”，否则所有项目输出（包括中间 HTML 文件和最终的 chm/HxS）都会添加到项目中。这会显着增加构建时间，尤其是在使用源控件时，因为需要检出现有文件或将其添加到源控件。根据使用 TFS 和一个中等项目的经验（该项目生成了数千个中间 HTML 文件），在源控件上花费的时间是其余构建时间的数倍（但这可能取决于项目大小、TFS 负载、网络等各种因素）。
使用图像
您可以在概念性文档中使用图像。所有图像必须放置在项目的 *Help\Art* 文件夹中，并且必须在 *Help\Settings\conceptual_art.xml* 文件中为每个图像定义一个 `<item>`。图像可以通过唯一 ID（而不是文件名）在整个项目中引用。一个项目如下所示：
<item id="myimage">
<image file="image.jpg">
<altText>Alternate text for the image.</altText>
</image>
</item>
定义了这一点后，您可以使用 `<mediaLink>` 节点来引用图像。
<mediaLink>
<image xlink:href="myimage" />
</mediaLink>
API 参考文档
当您将概念性文档和自动生成的 API 参考文档合并在一起时，您可能希望将两者放入某个特定的结构（或层次结构）中。您应该注意到，无论您从多少源构建自动生成的 API 参考文档，这些文档都可以放在主题层次结构中的一个位置。
如果您再次查看 *topics.xml* 文件，您会注意到这个节点：
<stoc project="Project" />
它代表了带有自动生成 API 参考的节点。它可以手动或从 Topics Explorer 放置在层次结构的任何位置。在此示例中，我将使其成为名为 API Reference 的根项的子项。
这是 *topics.xml* 文件已更新的方式：
<topics>
<topic id="679431bf-4adc-4f8b-a90d-012a4f14d6c4" file="Conceptual.aml" />
<topic id="0fa8f38b-522c-4894-9af8-cd6449d1b169" file="API Reference.aml">
<stoc project="Project" />
</topic>
</topics>
以及生成的 Help 1.x *.chm* 文件：
概念类型
DocProject 允许您创建多种概念性文档类型。可以使用 Topics Explorer 中的“插入新的概念性主题”命令添加新主题。以下 MAML 文档模板可用（对于其中大多数，标题不言自明）：
- 概念性
- 错误消息
- 词汇表
- 操作方法
- Orientation
- 参考（多种模板）
- 示例
- SDK 技术（多种模板）
- 故障排除
- UI 参考
- 演练
- 白皮书
- XML 参考
MAML 定义了一系列标签及其相互关系。架构位于 Sandcastle 安装文件夹下的 Schemas\Authoring 文件夹中。下表是这些架构的摘录。它显示了最重要的元素及其描述（和附加注释）。
| Tag | 描述 |
|---|---|
<para> |
para 元素描述一个段落。它是最基本的文档单元。 |
<content> |
此元素包含编写的内容。它可以是代码、部分或过程、链接或表格等任何内容。 |
<title> |
title 元素描述文档某个部分的名称。 |
<quote> |
quote 元素描述一个引用。 |
<summary> |
此元素包含当前项目的摘要、介绍或简短描述。此文本通常出现在主题中，也可能用作主题在链接到该主题时出现在跳转表中的描述。 |
<remarks> |
此元素包含对当前项目的详细讨论。 |
<comments> |
此元素包含一般性讨论。 |
<description> |
此元素包含一般性讨论。 |
<conclusion> |
此元素包含某个文档的结论。 |
<introduction> |
此元素包含某个文档的介绍。 |
<sections> |
此元素包含一组 section 元素。 |
<section> |
section 元素描述文档中的一个部分。section 元素支持递归。 |
<sectionSimple> |
sectionSimple 元素描述文档中的一个部分。此元素与 section 元素相似；但是，它不是递归的。 |
<glossary> |
glossary 元素描述一组术语及其定义。 |
<glossaryEntry> |
glossaryEntry 是词汇表中带有术语集的单个定义。 |
<relatedTopics> |
relatedTopics 用于链接到读者可能感兴趣的其他主题。 |
<procedure> |
此元素是过程的根。 |
<steps> |
此元素是过程中的一个步骤集合。 |
<step> |
此元素是过程中的一个步骤。 |
<list> |
list 元素描述应显示为列表的内容。class 属性描述列表类型，可以是“bullet”、“nobullet”或“ordered”。“class”属性是必需的。 |
<listItem> |
listItem 元素描述列表中的一个项。listItem 元素的内容将被视为一个单元。 |
<link> |
link 元素可以包含文本，但在构建时会丢弃此文本，而使用链接目标的实际标题，因此此元素中的文本是不可本地化的。 |
<externalLink> |
externalLink 元素描述 Microsoft 外部的链接，并且必须通过重定向方案进行管理。 |
<linkText> |
linkText 元素描述链接的文本。 |
<linkAlternateText> |
linkAlternateText 元素描述链接的替代文本，用于 Web 上的“alt 文本”。 |
<linkUri> |
linkUri 元素描述链接的 URI。 |
<mediaLink> |
media 元素表示任何类型的媒体对象。它旨在作为图像、音频和视频的占位符。渲染程序将负责以合理的方式渲染引用的对象。 |
<codeExamples> |
此元素是 codeExample 元素的集合。 |
<codeExample> |
此元素包含对代码示例的讨论。 |
<buildInstructions> |
此元素包含构建代码示例的说明。 |
<codeEntityReference> |
此元素包含对代码实体的引用。 |
<parameterReference> |
此元素包含对参数的引用。 |
在了解这些标签如何用于构建概念性主题之前，我们将特别关注 `codeEntityReference`。
codeEntityReference
此元素包含对代码实体的引用。它允许您在概念性主题和特定代码实体的 API 参考文档之间提供链接。这可能是一个类型、方法、属性等。元素文本必须是符合 ECMA 规范 定义格式的实体标识符。
该规范要求标识符：
- 字符串中没有空格。
- 第一部分是一个前缀，指示正在记录的成员类型，由一个字符后跟一个冒号组成。它定义了以下类型的成员：
- E：事件
- F：字段
- M：方法（包括构造函数、析构函数和运算符）
- N：命名空间
- P：属性和索引器
- T：类型（类、结构、委托、枚举和接口）
- !：错误字符串，字符串的其余部分提供有关错误的详细信息（例如，无法解析链接）。
- 字符串的第二部分是元素的完全限定名称，从命名空间根开始。
在标识符的第二部分方面，您必须遵守以下规则，您可以在此处 找到一套全面的示例。在下表中，在示例列中，Foo 是一个命名空间，Bar 是一个类，Func 是一个方法。
| 适用于 | 规则 | 示例 |
|---|---|---|
| 带参数的方法和属性 | 需要用括号括起来的参数列表。 | M:Foo.Bar.Func(System.Boolean) |
| 不带参数的方法和属性 | 省略括号。 | M:Foo.Bar.Func |
| 构造函数 | 使用 #ctor 而不是名称。如果构造函数带有参数，则参数列表的规则与方法相同。 | M:Foo.Bar.#ctor |
| 静态构造函数 | 使用 #cctor 而不是名称。如果构造函数带有参数，则参数列表的规则与方法相同。 | M:Foo.Bar.#cctor |
| 析构函数 | 使用 Finalize 作为方法名。 | M:Foo.Bar.Finalize |
| 参数 | 用逗号分隔，中间没有空格。参数由其完整的文档名称表示（基于其完全限定名称）。例如，int 变为 System.Int32，string 变为 System.String，依此类推。对于用户定义的类型也适用相同的规则。 | M:Foo.Bar.Func(System.Int32,System.String,Foo.Widget) |
out 和 ref 参数 |
在其类型名称后加上“@”字符。 | M:Foo.Bar.Func(System.Int32@) |
通过值传递的参数或 params |
没有特殊表示法 | |
| 定义泛型类型参数的参数 | 后面附加一个重音符“`”，后面跟着类型参数的数量；例如，C`1。对于嵌套类型，数量基于嵌套类型的新类型参数；例如，C`1.NestedC`2。 | T:Foo.Bar`1 |
| 数组参数 | 表示为 [lowerbound : size , ... , lowerbound : size]，其中逗号的数量是秩减一，并且每个维度的下界和大小（如果已知）以十进制表示。如果省略下界或大小，则省略它。如果省略某个维度的下界和大小，则也省略“:”。 |
M:Foo.Bar.Func(System.Int32[0:,0:]) |
| 交错数组参数 | 通过每个级别的“[]”表示。 | M:Foo.Bar.Func(System.Int32[],System.Int64[][]) |
| 指向 void 以外指针类型的参数 | 使用类型名称后的 * 表示。 | M:Foo.Bar.Func(System.Char*,Foo.Widget**) |
| 指向 void 的指针参数 | 由类型名称 System.Void 表示。 | M:Foo.Bar.Func(System.Void*) |
| 引用类型上泛型类型参数的参数 | 使用单个重音符“`”后跟类型参数的零基索引进行编码；例如，`0。 | M:Foo.Bar`1.Func(`0) |
| 使用泛型参数的方法的参数 | 使用双重音符“``”后跟类型参数的零基索引进行编码。 | M:Foo.Bar.Func(``0,``1) |
| 引用构造的泛型类型的参数 | 使用泛型类型后跟用花括号“{”和“}”括起来的逗号分隔的类型参数列表进行编码。 | M:Foo.Bar.Func(System.Collections.Generic.List{System.String}) |
说了这么多，让我们来看看几个最常见的概念模板。遍历所有模板没有意义；一旦您弄清楚了如何使用其中的一些，您就可以轻松地使用任何您认为适合您的主题的模板。正如您将看到的，这些内容类型非常灵活，没有明确的边界或区别；某些类型可以轻松地转换为其他类型。它们的目的在于为文档记录主题提供快速的开始，并避免每次编写新文档时都从头开始定义文档结构。
概念模板
这是一个简单但可能是最常用的概念主题。顾名思义，它相当通用，可以用于任何未通过其他模板定义的用途。概念模板包含一个摘要、一个介绍、一个部分和一个相关主题。摘要元素是可选的，介绍是强制性的，必须至少有一个部分或一个过程。相关主题元素也是强制性的，但它可以是空的。下面是一个通用概念主题的示例以及生成的帮助页面的屏幕截图。
<topic id="679431bf-4adc-4f8b-a90d-012a4f14d6c4" revisionNumber="0">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<summary>
<para>This is a simple summary of a conceptual topic.</para>
</summary>
<introduction>
<para>The conceptual template is the most used template.</para>
</introduction>
<section>
<title>The section title</title>
<content>
<para>
The para element describes a paragraph.
It is the most basic documentation unit.
</para>
<list class="bullet">
<listItem>
<para>this is an item</para>
</listItem>
<listItem>
<para>this is another item</para>
</listItem>
</list>
<para>
This is a link to the documentation of
<codeEntityReference>T:DemoLibrary.IMath`1</codeEntityReference> interface.
</para>
</content>
</section>
<relatedTopics>
<link xlink:href="cc595a59-57cd-493d-b059-297ffe93290d" />
</relatedTopics>
</developerConceptualDocument>
</topic>
词汇表
术语表是术语及其定义的字母顺序列表。通常，术语表包含文档中新引入的、不常见的或专门的术语。MAML 为术语表定义了一个名为“Glossary”的模板。该模板包含一个词汇表，该词汇表有一个标题，并且至少有一个词汇表条目或一个词汇表分区（词汇表内的部分），它又包含至少一个词汇表条目。每个条目至少包含一个术语和一个定义。下面是词汇表的示例以及结果的屏幕截图。
<?xml version="1.0" encoding="utf-8"?>
<topic id="cc595a59-57cd-493d-b059-297ffe93290d" revisionNumber="0">
<developerGlossaryDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<glossary>
<title>This is the title of the glossary.</title>
<glossaryDiv>
<title>This is a glossary division</title>
<glossaryEntry>
<terms>
<term termClass="used">blogging</term>
</terms>
<definition>
<para>writing on or otherwise using online journals known as web logs or blogs</para>
</definition>
</glossaryEntry>
<glossaryEntry>
<terms>
<term termClass="used">tweet</term>
</terms>
<definition>
<para>a small message sent by a user of the website Twitter.</para>
</definition>
</glossaryEntry>
</glossaryDiv>
</glossary>
</developerGlossaryDocument>
</topic>
操作方法
“操作方法”主题用于记录某人必须执行的特定过程。该模板包括一个可选摘要、一个强制性介绍、一个过程（也可以是一个部分）和相关主题。其他元素是可能的，例如代码示例、构建说明或安全性。过程是一系列步骤（以有序方式显示 - 使用数字或项目符号）。步骤的内容可以是任何文档，包括其他过程。
<?xml version="1.0" encoding="utf-8"?>
<topic id="8935f12d-9594-43cc-9ec5-1cafa88359e3" revisionNumber="0">
<developerHowToDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<summary>
<para>This is the summary of this how to.</para>
</summary>
<introduction>
<para>This is a simplified version of the How to template. It only contains a procedure.</para>
</introduction>
<procedure>
<title>How to write a procedure</title>
<steps class="ordered">
<step>
<content>
<para>add a new topic from a "how to" template</para>
</content>
</step>
<step>
<content>
<para>remove the unnecessary elements from the template</para>
</content>
</step>
<step>
<content>
<para>document the steps of the procedure</para>
</content>
</step>
</steps>
</procedure>
<relatedTopics>
</relatedTopics>
</developerHowToDocument>
</topic>
演练
演练与“操作方法”类似，但更复杂一些。“操作方法”用于回答与某个明确定义的主题相关的一个或多个特定问题。演练可以引用更广泛的主题，或一系列人们需要遵循的过程。演练实际上可以是“操作方法”的集合。演练模板包含一个可选摘要、一个介绍、一个先决条件部分、一个过程、一个后续步骤部分和相关主题。在更简单的形式中，演练可以只包含摘要、介绍、过程和相关主题，这与“操作方法”模板的结构完全相同。
<?xml version="1.0" encoding="utf-8"?>
<topic id="4a84d8eb-7880-4a1a-99e1-fdf0527a22d5" revisionNumber="0">
<developerWalkthroughDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<summary>
<para>This is a simple walkthrough.</para>
</summary>
<introduction>
<para>In this walkthrough we will see how to write walktroughs.</para>
</introduction>
<prerequisites>
<content>
<para>You need the following prerequisites:</para>
<list class="bullet">
<listItem>
<para>HTML Help Workshop</para>
</listItem>
<listItem>
<para>Sandcastle and DocProject</para>
</listItem>
<listItem>
<para>Visual Studio</para>
</listItem>
</list>
</content>
</prerequisites>
<!-- One or more procedure or section elements -->
<procedure>
<title>How to write a walkthrough</title>
<steps class="ordered">
<step>
<content>
<para>add a new topics using the walkthrough template</para>
</content>
</step>
<step>
<content>
<para>document the steps of the walkthrough</para>
</content>
</step>
</steps>
</procedure>
<nextSteps>
<content>
<para>After reading this walk-through read the troubleshooting template documentation.</para>
</content>
</nextSteps>
<relatedTopics></relatedTopics>
</developerWalkthroughDocument>
</topic>
结论
Sandcastle 和 DocProject 使得记录您的产品、库或任何其他需要记录的项目相对容易。您可以编写概念性文档（自定义主题、FAQ、演练、术语表等）和 API 参考文档（从托管程序集和带注释的 XML 文件自动生成），甚至可以将它们混合在一起。用于构建文档的工具都是免费的，并且设置相对简单。在本文中，我们了解了如何开始使用 DocProject，并查看了一些概念主题模板。您需要做的是通过实践这些模板和 MAML 定义的标签，从而构建您的文档。