需求描述
我们工作中需要向客户发布软件Specification说明书,它包含软件功能描述,使用方式,以及各接口的描述,同时要识别每个版本中的接口变更,形成ReleaseNotes并通知客户。
我们的 Specification是使用Word文档来承载,开发人员每次修改时无法做review,每轮迭代完成后,会遇到两个问题:
- 开发人员每次对Specification修改,无法做Review,无法保障每次修改的质量
- 经过一轮迭代之后,开发人员无法准确回忆此过程当中的修改,哪些是涉及的接口变更的
解决方案
经过设计师和架构师们的讨论,解决问题需使用以下的流程控制:
- 所有有的Specification必须要经过git提交和review,才能做每次修改作review,保证内容经过检视
- 如果涉及接口的变更,需要在ChangeLog是按固定的格式填好,每轮迭代完成之后,通过脚本自动抽取并形成变更列表
我提出了Markdown方案,开发人员使用Markdown本地编辑器写Specification,确认修改无误之后通过git提交,涉及接口描述变更的,按规定的ChangeLog格式填好信息提交。经过其它工程师review无意见之后,再入库。
经多方讨论后同意使用Markdown方案,属于资料工程架构的重新设计。
为了能让工程师专注Specification内容的编写,需要选用适合的Markdown编辑器,下面是对几款主流的工具做对比分析。
Markdown编辑器对比分析
我们工作平台是window,从易用性来说,只选用window平台的。从公司选用软件的要求,最好或者尽量不要选用商用付费软件,开源是最优的选择。
目前只分析了Atom和MarkdownPad2两工具。 有更好方案介绍的朋友们,请留言,或者email (lyt2008bj#163.com) 告知我,谢谢。
语法支持
工具 | 标题 | 粗体与斜体 | 列表 | 引用 | 图片 | 链接 | 表格 | 代码高亮 | 分割线 |
---|---|---|---|---|---|---|---|---|---|
Atom | Yes | Yes | Yes | yes | yes | yes | yes | yes | yes |
MarkdownPad2 | Yes | Yes | Yes | yes | Yes | Yes | No(付费版才有此功能) | No | Yes |
对于软件Specification,表格和代码高亮是必不可少的,这是最基础的要求。如果能支持流程图,UML图,那就更优了。
易用性
工具 | 同步预览 | md和预览同时滑动 | 编辑时图片预览 | 导出类型 | 显示效果 | 文件浏览管理 |
---|---|---|---|---|---|---|
Atom | Yes | No | Yes | HTML | 可制定 | Yes |
MarkdownPad2 | Yes | Yes | Yes | HTML、PDF | 可制定 | No |
易用性也是非常重要的,因为使用工具的主体是人,易用性关系到生产率。
Atom 一个致命令的不足是,MD内容和预览内容无法实现同时滑动,也有另一个优点那就支持文件管理,满足Specification由多个md文件组成。
其它项
工具 | 软件类型 | 收费 | 扩展性 |
---|---|---|---|
Atom | 开源 | 免费 | 插件 |
MarkdownPad2 | 商业 | 付费 | 样式制定 |
Atom属于开源,扩展性更优,当属于不二之选。
选型结果
经多个维度的评估,Atom比MarkdownPad2更适合我们的项目,唯一不足是编辑时无法实现同步滑动功能。
向各路朋友高手请教
各位是否有更好的工具推荐,如果有,麻烦请在下面评论,或者发送到我邮箱,谢谢!
如果你对工具很了解,还麻烦帮我将上面的属性信息填好到评论或邮件里,那就真是太感谢了。
另外工程师按每个特性写完一个md文件之后,有什么好的工具, 可以将这些md文件转换成chm文档或者word文档,还请有经验的朋友介绍方法。