如何在Sandcastle中编写指南、问答类非代码文档

方案1：用Sandcastle官方的「概念性内容」功能 #

这是专门用来加指南、问答这类非API文档的规范方式：

• 在Sandcastle项目的资源管理器里，右键点击「Conceptual Content」节点，选择「Add New Item」，直接创建.aml格式的概念文档——Sandcastle自带基础编辑支持，不用额外找外部工具
• 编辑时不用写复杂的AML结构，用简化模板即可：比如做问答，用<section>包裹内容，<title>写问题，<content>里填答案；指南类可以拆成多个<section>分模块组织
• 务必去项目属性的「Build」选项卡，勾选「Include conceptual content」，否则构建时这些文档不会被整合进最终输出。生成的文档里会单独出现「概念」或「指南」导航栏，和API文档清晰区分

方案2：改造XML注释方案（替代之前的独立命名空间方法） #

如果不想碰AML，就把你之前的思路调整下，去掉多余的class标记：

• 新建一个空的静态类，比如public static class DocumentationGuides，里面不要写任何代码逻辑，纯当文档占位符
• 在这个类的XML注释里，用<include>标签引用外部的.md或格式化XML文档内容，Sandcastle可以解析带格式的注释内容
• 接着在Sandcastle的「Visibility」设置中，把这个类的「Type」设为「Hidden」，但保留注释内容的显示——这样最终文档只会展示你写的指南内容，不会出现class定义和代码结构

方案3：简化AML编写的工具技巧 #

要是觉得AML写着费劲，试试这些小技巧：

• 用Visual Studio自带的XML编辑器打开.aml文件，它会自动提示AML标签，还有语法高亮，能减少出错概率
• 先把内容写成Markdown，再用本地的Pandoc工具转换成AML格式，再导入Sandcastle项目，比直接写AML轻松很多

内容的提问来源于stack exchange，提问作者stUStiat