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

 

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