如何为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>

 

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