团队文档管理工具

最近所在的组织在思考需求文档如何管理,趁这个机会将自己以往使用过的文档管理一并整理,供大家参考。

需求文档的核心目的在于快速、准确的向相关方传递产品设计理念和方案。易用、快速、可传承、安全与持续维护、成本是选择管理模式的主要维度。

管理目的

需求文档管理可能是产品设计环节产品经理最常进行的工作。我们需要综合考虑各项因素:

  • 易用
  • 快速访问
  • 可传承
  • 安全与持续维护
  • 成本

易用与效率

一个交互体验良好、稳定的管理工具和方式,有助于让文档编写人员工作时可以保持一个良好的心态,而简洁的界面也可以让人员集中注意力编写文档。

我们还需要考虑行业和组织特性:若文档涉及大量计算推导,对数学公式的支持就会变得尤为重要。对于虚拟组织或有网上讨论问题的文化,在线讨论功能就很实用。

快速访问

可传承

基于 web 的产品基本避免了对客户端环境的依赖。

对于较为较为复杂的文档可采用 word 或 axure 等较为成熟的商用软件或者开源软件,有利于避免日后依赖的编辑软件不再维护的尴尬。

但对于很多开源软件,也意味着功能较为单一和文档不兼容,再日后迁移至其它平台(比如上云)或更换其它软件会带来另外的工作量。

安全与持续维护

除了大牌且持续维护的平台,尽可能的不要使用选择互联网管理产品,毕竟组织内文档往往是重要的资产,再谨慎也不为过。

一些大牌的平台往往将更灵活的安全选项设为收费项目,当发展到一定程度(如:出现了多个项目组、较复杂的层级、需要在该平台上管理多种类型的文档)时不妨考虑。

通常也不建议将自行构建或私有化部署的管理平台暴露到公网,通常这类软件在设计都不像那些面对客户的产品那样有完善的安全策略或有足够的运维资源支撑。

成本

  • 尽量采用开源系统

常用工具及管理方式

SVN

SVN是一种开源的版本控制方法,拥有版本和分支管理等特性。每个软件行业从业者应当对其都非常熟悉了。通常产品经理们只将其作为版本管理的工具。有如 TortoiseSVN(Win)、
Versions(MAC)等客户端。基本上是0成本的管理工具。

作为最入门的管理方式,可以使用文档编辑工具编写的文档以独立文件形式存在,以一个发布版本为一个文件夹组织,以文件名进行识别,定期(如:每日、归档时)将档案提交至SVN上,以让组织内部其他伙伴可以查看。

GitBook

GitBook 是一款与 GitHub 同门产品。是一款专门定位于文档管理的工具。

通过 「编辑 – 检查 – 合并」的工作流程对文档进行迭代编辑,支持 markdown, 内建简单的API文档、Q&A模版。

在内容上支持网页插入图片、公式等。甚至对于接口文档都有内置的内容块,非常实用。

GitBook 的工作流程

免费版的 GitBook 可以发布一个公开及一个私人空间,还可以指定一个自定义域名(CNAME),作为公开的说明书等公开文档来说非常专业实用。

考虑到软件的持续迭代,GitBook 自带了「 释出版本管理」的功能,方便对同一个产品的不同版本分别维护。当新增一个版本的时,将从标记为主板本的文档中拉出分支。

GitBook的释出版本管理

页面布局可以调整的空间不大,仅支持自定义标题、头部菜单和主色调,属于简单实用型的工具。

语雀

一款由蚂蚁金服孵化的知识分享工具,功能全面且免费。适用于集体文档编辑和分享,作为自己的知识管理工具甚至用来写个 blog 都是很适合的,界面清爽。

文档的组织以知识库为单位,有三种类型的知识库可供选择:

  • 文档: 一个目录(作为封面)和若干个文档。
  • 专栏:类似一个博客,一个预览列表(作为封面)和若干个文档。
  • 画板:分享相册、原型稿类型的知识库。

文档编辑界面类似一般的文本编辑工具,支持大纲层级查看,非常方便。支持的内容类型广泛,支持在文档中添加 Youku 和 B 站视频,或许在某些场景有用。

协作方面,编辑者可以反复在线编辑,直到需要发布的时候才将状态更新为发布并添加至目录。关键版本时发布还可以向组内成员发送通知,而平时的编辑则不过多打扰。

还有一个亮点:同蚂蚁体验科技家族的 Kitchen 工具支持将 Sketch 一键上传到语雀,对于有设计师参与的团队来说,使用画板知识库来分享设计稿是一个讨巧的功能。可惜的是并没与对于 Axure 的支持。

石墨文档等

GitHub

对于崇尚使用且几乎是仅使用 markdown 的团队,GitHub提供了一个基于在线,并且和开发习惯非常吻合的管理方式。

将 master 视为发行版本,在进行新一期的版本规划时创建分支,当规划完毕后合并至 master,反复的循环。

同时,利用 GitHub 保持与回顾代码一致的方式对文档进行追溯,每个人都可以轻松的对代码进行维护并且找到其他人更新过的地方。

使用 GitHub 管理需求文档的版本
使用 GitHub 管理需求文档的版本

至于缺点,由于几乎是一个纯文本工具,使用 markdown 编写文档无疑是一个挑战,对于需要嵌入图片的文档处理起来会稍微费事一些。

即使如此,对于一些简单的文档、原则类的文档,这样管理还是很实用的。

商用工具

商用软件对于中小型团队来说或许来说成本太高。但商用软件往往有着良好的商业技术支持、插件生态和可集成性。虽然往往给人笨重的印象但往往还是很适应大企业的管理方式的,尤其是当统一品牌一系列工具一齐实施的组织,往往还是很爽的。

Confluence