作者:小马哥 | 来源:互联网 | 2023-08-17 09:01
需求描述我们工作中需要向客户发布软件Specification说明书,它包含软件功能描述,使用方式,以及各接口的描述,同时要识别每个版本中的接口变更,形成ReleaseNotes并通知客户。
需求描述
我们工作中需要向客户发布软件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文档,还请有经验的朋友介绍方法。