Markdown编辑器对比分析

时间:2022-03-14 17:52:09

需求描述

我们工作中需要向客户发布软件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文档,还请有经验的朋友介绍方法。