【经验谈】技术文档常用写作绘图工具

Authoring Tools

工具名	优点	缺点
MS Word	- 大众软件，群众基础广	- 样式不稳定，极易产生派生样式 - 应用样式时，容易出现无法预知的错误 - 大文档生成PDF时耗时很长
Acrobat FrameMaker	- 专业Authoring Tool - 样式稳定 - 便于多个writer协同合作 - 提供inset功能便于内容重用 - 生成PDF流畅	- 审阅者一般没有安装该工具，必须生成PDF送审 (解决方法：Writer可用Abode Professional 将PDF转成WORD；或生成PDF时，启用“Read Commenting Enabled”）
XML Authoring Tool such as OxyGen	* 适于内容重用度高的文档 ； * 文档样式可根据CSS设定灵活呈现 * 支持生成各种输出格式 （html, PDF) * 最后，通过Information architect预先设定每类Topic的必需元素，可以做到通过工具，保证不同writer在topic上写作风格统一，不遗失Topic中的任何必需元素。我认为它是Topic-based writing实现的一个利器。	- 用Acrolinx做语法检查时，必须一个个dita file检查，有些费力 - 写作编辑时看到的是很单调的近乎txt的文本，视觉效果不好 - 需要有经验的writer来定制与维护样式
Atlassian Confluence	- 共享式文档开发平台；- 支持Word、Excel文件导入 - 可输出业内通用各种文档样式 - 可生成HTML文件从而与当下流行的File Server文档发布模式契合 - 丰富的第三方插件 （例如可购Workflow插件从而streamline整个写作审阅/编辑/发布流程）- 可通过CSS文件自定义样式	- 可查看Revision History, 但没有自带版本管理 (需购插件）- 需要有经验的writer来定制与维护样式
Adobe Robohelp	- 在线文件写作与生成工具 - 支持Word与FM file倒入 - 自定义skin, cover...	- 需要有经验的writer来定制与维护样式库
Markdown	- 网页文档写作工具 （多用于软件类产品文档）最进接触到。- 使用markdown工具编写文档，通过静态网站生成工具生成网页文档 （如需了解相关工具，可在“知乎”搜索<软件技术文档代码化现象>一文	- Markdown对于写的朋友应该不会陌生。我在使用过程中有不少格式上的困惑，比如表格中的bulleted point如何解决...听说过通过coding可以解决。但还没有实践过。- WYSIWYG功能差些，虽然可以开即时显示窗口。

Confluence文档host在服务器上，若无版本管理插件，无法实现版本管理。上表中其它工具都可利用公司现有的代码管理软件，实现版本管理。MA代码管理工具使用的是Perforce， UT使用的是Clearcase。

Diagramming Tools

• SnagIt--截图工具，可修图。
• MS Visio--流程图，组网网绘制工具。可自定义加载stencils。

说明：Visio可将图片存在SNG格式，该格式图片中的文本信息支持全文搜索。(2007以上版本Visio可直接支持，2007版需做一个小设置，网上可搜到方法）

PDF编辑工具

Acrobat Adobe Professional -- 可编辑PDF文件，可把FM, Word文档输出成PDF。在审阅时，支持把PDF文件放在File Server上，发起共享式评审。

语法与写作样式检查工具

Acrolinx -- 可做语法与自定写作规则定义，但价格有些贵。不过保证了文档写作的风格，大大提高协同文档的一致性。

MA文档发布形式

• PDFs published on Moody's Analytics Support Web
• Online help embedded in the RO S/W
• HTML Documents hosted on the MA Portal File Server

MA 写作规范

• Writing Style Guide
• Graphic Style Guide
• Trademark Guidelines