如何为SDK编写专业的用户指南

我在原来的公司上班时，所有的用户手册都有一个Document Team来负责。每次添加一个新的功能或者对功能进行更改，我们都需要开一个Document Bug，然后Document Team会根据描述信息来更新文档，最终给用户提供一个全面、符合当前软件系统的用户指南。现在我们团队也正在开发一个OSGi.NET平台的产品，这种SDK类的产品如果没有一个专业的用户指南就显得很不专业了。这个产品的RC2版本还没有很好的文档，仅是提供一个基于Word的用户指南和一个API的CHM说明书。现在我们正在为这个产品编写专业的用户指南，因此我就把如何使用工具来编写用户指南的过程在这里做一个描述。

1 用户指南效果图

UIOSP是一个基于OSGi.NET的动态模块化平台，通俗一点，就是一个插件平台。目前用户指南已经编写到“如何创建主程序”这一节了。用户指南由两大部分组成：（1）平台使用指南；（2）API说明书。CHM格式的帮助文档如下所示：

当然，你还可以生成HTML的格式，如下：

接下来我将分别介绍如何来编写平台使用指南和API说明书，由于API说明书比较简单，因此，我把API说明书编写介绍放在前面。

2 如何编写用户指南

2.1 工具

这个用户指南是使用Sandcastle和SandcastleBuilder这两个工具来编写的，你可以从http://sandcastle.codeplex.com/和http://shfb.codeplex.com/站点上下载到这两个工具。安装完成后，你可以运行Sandcastle Help File Builder来创建一个帮助文档项目，我在《[产品开发经验总结] 软件产品背后的冰山一角》已经提到这2个工具了。如下图，我新建了一个UIOSP User Guide的项目，在Documentation Sources添加了UIShell.OSGi.dll和UIShell.OSGi.WebExtension.dll两个API Doc Sources。此外，我还创建了一个UserGuide.content的“平台使用指南”目录。最还，更改了一些用户手册的属性，比如HelpFileFormat我指定的是HtmlHelp1和WebSite。

2.2 API说明书编写

API说明书的编写比较简单，它可以根据我们编写的类的注释生成的XML文件自动的创建出来。API说明书编写的步骤如下：

（1）为类添加注释

为类或者方法添加注释的方式很简单，只要以“///”开头，VS IDE就自动给你生成如下格式的注释。不过，它默认的只有Summary、参数和返回值。

1 /// <summary>
2 ///
3 /// </summary>
4 /// <typeparam name="ServiceInterface"></typeparam>
5 /// <param name="serviceInstance"></param>
6 public void AddService<ServiceInterface>(object serviceInstance) 
7 { 
8         Framework.AddSystemService(typeof(ServiceInterface), serviceInstance); 
9 }

VS IDE的注释还提供了其它的XMl节点，比如Example、Code、Para等，以下是使用这些节点编写的一个API说明，它在说明里面除了简单注释之外，还举了一个使用API的例子。

1 /// <summary>
2 /// 添加一个全局服务。 
3 /// </summary>
4 /// <typeparam name="ServiceInterface">服务接口。</typeparam>
5 /// <param name="serviceInstance">服务实现。</param>
6 /// <example>
7 /// <para>该方法可以在BundleRuntime启动之前添加一个全局服务，从而所有的插件都可以获取并使用。以下是其用法。</para>
8 /// <code>
9 /// using(BundleRuntime bundleRuntime = new BundleRuntime(@"D:\UIOSP\MyShell\plugins")) 
10 /// { 
11 ///     Console.WriteLine("Enter 'exit' key to exit..."); 
12 ///     // 添加一个全局服务。 
13 ///     bundleRuntime.AddService<![CDATA[<ILogService>]]>(new MyLogService()); 
14 ///     bundleRuntime.Start(); // 启动模块插件运行时。 
15 ///     Console.ReadLine(); 
16 /// } 
17 /// </code>
18 /// </example>
19 public void AddService<ServiceInterface>(object serviceInstance) 
20 { 
21     Framework.AddSystemService(typeof(ServiceInterface), serviceInstance); 
22 }

当生成API之后，其对应的内容如下图所示。它包含了方法的注释、参数的注释、使用语法、示例。

一般而言，常见的注释XML如下：

1 <c>text</c> -- 文本中指定为代码 
2 <code>content</code> -- 多行代码 
3 <para>content</para> -- 段落 
4 <see cref="member"/> -- 链接 
5 <param> -- 参数 
6 <seealso cref="member"/> -- 显示also列表 
7 <example>description</example> -- 示例
8 <exception cref="System.Exception">Thrown when...</exception> -- Exception声明 
9 <remarks>description</remarks> -- 备注
10 <list type="bullet" | "number" | "table"> -- 列表 
11 <listheader>
12 <term>term</term>
13 <description>description</description>
14 </listheader>
15 <item>
16 <term>term</term>
17 <description>description</description>
18 </item>
19 </list>

（2）更改项目属性生成注释XML文件

这个步骤比较简单，只需要把“XML文档文件”勾上并指定生成目录就可以了。

（3）添加Doc Sources

接着我们可以使用SandcastleBuilder添加Doc Sources，然后添加一个dll就可以了。

（4）设置需要生成的API的类集合

对于一个SDK而言，暴露过多没有意义的API会对用户造成混淆，因此，我们可以通过SandcastleBuilder来设置不需要生成API的命名空间或者类。如下图所示，你可以通过项目的ApiFilter来设置过滤。

2.3 平台使用指南编写

2.3.1 创建平台使用指南的目录

首先点击项目属性右键，添加“New Item”，选择Content Layout，即文档目录。

然后双击Layout文件，在左侧将显示给目录内容，这样，你可以为目录添加一些节点。首先点击“右键”，然后选择“Add Sibling Topic”来添加一个一级节点。

创建完成后，你可以为一级节点通过“Add Child Topic”菜单添加字节点，这样你就可以构建像UIOSP用户指南的目录了。

2.3.2 编写指南文件

在上面描述的，每一级目录都有一个aml文件，这个文件是这级目录的内容。接下来我们需要填充一些内容。以下示例建立了一个具有示例代码、图片的AML文件。

1 <?xml version="1.0" encoding="utf-8"?>
2 <topic id="73dfeeb5-c3c9-444f-b23d-b7dc24d3cd2f" revisionNumber="1">
3 <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
4 <introduction>
5 <para>该小节向您介绍如何创建Movies插件。该插件为整个应用系统提供了“Movie List”页面——Default.aspx和“Create New Movie”页面——CreateNew.aspx。</para>
6 </introduction>
7 <section address="CreatePlugin">
8 <title>创建插件项目</title>
9 <content>
10 <para>添加一个新建项目，项目模板为UIOSP目录下的“ASP.NET Web空白插件”，名为MoviesPlugin，项目目录位于Plugins下。</para>
11 </content>
12 </section>
13 <section address="CreateModel">
14 <title>创建数据模型</title>
15 <content>
16 <para>添加一个Movie类，这个类定义了这个插件的数据模型，其定义如下。目前该类只是提供了一些模拟的数据。</para>
17 <code language="cs">
18 <![CDATA[
19 using System; 
20 using System.Collections.Generic; 
21 using System.Linq; 
22 using System.Web;
23 namespace MoviesPlugin.Model 
24 { 
25     /// <summary> 
26     /// Movie实体定义。 
27     /// </summary> 
28     public partial class Movie 
29     { 
30         public string Title { get; set; } 
31         public DateTime ReleaseDate { get; set; } 
32         public string Genre { get; set; } 
33         public string Rating { get; set; } 
34         public float Price { get; set; } 
35     }
36 } 
37 ]]>
38 </code>
39 </content>
40 </section>
41 <section address="CreateCreateNewPage">
42 <title>创建CreateNew.aspx</title>
43 <content>
44 <para>到目前为止，MoviesPlugin已经创建完毕。接下来我们将创建一个可重用的LogsPlugin插件，并利用它提供的服务来记录Movie记录操作日志。关于目前解决方案的内容，请查看“Step2-MoviesPlugin.zip”文件，创建的MoviesPlugin插件内容如图3-17所示。</para>
45 <para>
46 <mediaLink>
47 <caption><legacyBold>图3-17 MoviesPlugin插件内容</legacyBold></caption>
48 <image xlink:href="3_17_MoviesPluginContentScreen"/>
49 </mediaLink>
50 </para>
51 </content>
52 </section>
53 </developerConceptualDocument>
54 </topic>

图片通过以下XML来添加。

        <para>
            <mediaLink>
                 <caption><legacyBold>图3-17 MoviesPlugin插件内容</legacyBold></caption>
                 <image xlink:href="3_17_MoviesPluginContentScreen"/>
             </mediaLink>
        </para>

代码通过以下XMl来添加。

<code language="cs">
<![CDATA[
using System;
……

]]>
</code>

有关图文并茂、包括示例代码的帮助编写就先简单的介绍到这。：）

转载于:https://www.cnblogs.com/jasmine_xm/archive/2010/10/18/1854609.html