查看原文
其他

用更优雅的方式写产品文档

Juuun codesigner 2022-07-14

作为互联网公司的产品经理,我们应该使用一种更加现代化、更加优雅的方式去写产品文档。

最近在写产品文档,在此之前我思考了一下该使用什么工具。结合产品文档的性质和我自己的需求点,总结了一下大概需要满足以下几点:

  • 高效书写,更专注于内容

  • 可以生成便于阅读的形式

  • 可在线预览与分享

  • 有历史版本记录

  • 可多人协作


经过几番尝试,最后我决定使用 Markdown 来编写文档,使用 Git 来做历史版本管理。同时在 Cloud Studio 上在线书写,并使用 Docsify 将其构建成一个网站,再将其部署在 CODING Pages 上,这样就可以生成一个在线网址,方便分享,并且也可以实时更新实时发布。

工具或技术介绍

对于不了解技术的朋友来说,看到这些英文单词会一头雾水,我先简要介绍一下它们。

Markdown

Markdown 是一种轻量级标记语言,可以将它看作一种代码语言,就像 HTML 一样,它可以将指定格式的文本转换成不同的样式。如下图,你只需要对文字加一些特别的标注,比如前面加两个 #,或者用 ** 将其包起来,就可以轻易地渲染出不同的文字样式。


Markdown 的好处是,你只需要记住这些简单的规则(实际上多写几次就记住了),就可以完全专注于内容,手不离键盘完成一篇样式丰富的文章编写。

详细的介绍参见《Markdown 完全入门(上)》

链接:https://sspai.com/post/36610

Git

Git 是一种版本控制技术,它的出现使得分布式协作成为了可能。简单来说,就是多个人分别在自己的电脑上编写代码,这些代码会通过一个统一的远程代码仓库进行同步(可以理解为一个网盘)。每个人修改一些内容之后先写明修改了什么,这一步叫做提交,再上传到远程仓库,这一步叫做推送。假如别人也有修改推送到了远程仓库,你就要先把对方的修改下载下来,这叫做拉取。


这样,本地代码和远程仓库中都会记录着每个人的提交,每一次修改都可以追溯,使得查看历史、恢复代码就都变得简单了。

详细的介绍参见《用玩游戏的方式学习 Git》

链接:https://sspai.com/post/47694

Docsify

Docsify(https://docsify.js.org/#/zh-cn)是一个动态生成文档网站的工具。你只需要创建一个 index.html 文件,并使用 Markdown 编写多个文档放在同一目录下,就可以自动搭建成一个小型的文档网站。


CODING Pages

CODING 是代码托管平台,可以作为我们在前面提到的 Git 远程仓库。Pages 是 CODING 提供的一项服务,可以将我们的代码生成一个在线网站。我们将代码同步至此,并使用 Pages 就可以将文档生成在线网站,方便分享。

Cloud Studio

Cloud Studio 是 CODING 推出的一款在线代码编辑器,而且自带一些软件环境。因为 Docsify 在本地预览需要安装一些软件环境,比较麻烦,所以我们选择使用在线编辑器,就不用安装啦。

怎么做?

介绍完了我们需要使用的工具或技术,下面来讲讲如何搭建这个产品文档网站。

创建账号

因为 CODING 和 Cloud Studio 现在已经变为腾讯云开发者平台(https://dev.tencent.com)下的应用,所以我们需要先去注册一个腾讯云开发者平台账号,这部分就不再多说。

创建工作空间

在 Cloud Studio 中,工作空间就是一个项目,我们的产品文档所有文件都存储在里面。进入 Cloud Studio 控制台(https://studio.dev.tencent.com/dashboard/workspace),点击上面的新建工作空间卡片,进入创建页面。


首先,填写一个项目名,比如我填写的是 product-docs(不能是中文哦);接着,我们在下面选择「从模板创建」,并选择 Blank 模板,也就是一个空项目。


然后,点击「创建」就可以成功创建一个工作空间。

安装 Docsify

点击刚才创建好的工作空间卡片,稍等一会就可以看到一个云端代码编辑器出现在眼前。


先简单介绍一下这个界面。它主要包含四大块:文件目录、代码编辑区、功能区和终端,文件目录就是我们按层级摆放的文档文件,代码编辑区是我们写文档的地方,功能区提供了一些额外的功能(一会会用到一些),终端是我们安装环境和 Docsify、执行 Git 命令的地方。


在写作之前我们先安装一下 Docsify,它可以帮助我们实时预览自己的文档效果。因为它是依赖 Node.js 环境,所以先点击右边的添加环境来切换到 Node.js 环境。


这里说的安装 Docsify 你可以类比理解为在电脑上安装一个 Photoshop 软件,不同的是安装和使用 Photoshop 整个过程都是可视的、图形化的界面操作,而安装和使用 Docsify 都是在终端中使用命令行进行的。

我们打开底部的终端,将 sudo yarn global add docsify-cli 复制粘贴进去,回车执行,一小会就安装好了。


这时候我们就可以使用它了。继续在终端中执行 docsify init ./docs 进行初始化,它会创建一个文档文件夹。此时文件目录中会多一个 docs 文件夹,我们就在这里面写文档。

编写文档,实时预览

docs 文件夹下面的 README.md 就是文档的第一篇,你可以在里面新建文件夹或者 md 后缀的文件,就可以写出多篇文档。现在我们预览一下这个文档的效果,在终端执行 docsify serve ./docs,它的作用是开启一个网页服务,这样你就可以实时预览由这些文档生成的网页了。

运行后,它会提示我们当前网页已运行在 http://localhost:3000 上,不过这个链接是不能直接访问的。


我们打开右边的访问链接,将输入框中的数字改成 3000,再点击右边的「创建连接」,在下方就会生成一条访问链接。你可以将鼠标放在二维码图表上来查看二维码并扫码访问,也可以直接点击蓝色的链接访问。


文档已经生成了,左侧是目录,有测试内容,不过文字太少看不太出来。


我们来改一下 docs 目录下的 README.md 中的文字试试。


保存后,刷新一下刚才的页面,可以看到我们刚才的改动已经生效了。

上传至代码仓库,更新至 Pages

不过刚才的预览方式只是临时的,我们想要生成一个永久链接的话,需要将代码上传到 CODING 代码仓库,并使用它的 Pages 功能来生成网站。

依次点击顶部菜单的「版本->提交」,进入代码提交页面。


点击左上角的全选,选中所有文件,同时在下面的输入框中填写这次提交的内容,再点击右下角的「确认」,就可以将这一次新增的文件提交到暂存区。


这时候,文件还没有同步到代码仓库,只是存到了暂存区。我们需要再次点击顶部菜单的「版本->推送」,将代码同步过去。


同步成功后,我们回到 Cloud Studio 控制台(https://studio.dev.tencent.com/dashboard/workspace),点击这个工作空间的右上角的小书,它就是对应的代码仓库链接。


可以发现我们刚才的提交动态已经显示在这里了。


点击左侧的「代码」,展开代码子菜单,再进入「Pages 服务」页面。勾选服务声明,再点击「一键开启 Coding Pages」按钮,开启 Pages 服务。


它会自动帮我们部署一次,但是这个部署的是根目录下的文件,而我们的文件都在 docs 目录下,所以我们需要自己改一下。


点击上图中右上角的齿轮图标,进入设置页面。在代码分支这里选择第二个选项,并点击「部署」按钮,即完成部署。


此时会返回到部署信息页面,等下面的部署信息显示成功之后,点击上面的链接,就可以看到我们的文档网站啦。

高级配置

Docsify 还有很多高级配置,比如设置封面、顶部导航、主题切换等等,你可以参考官方文档(https://docsify.js.org/#/zh-cn)。在 CODING Pages 这边也可以进行多种高级配置,比如绑定一个自定义域名等等,你可以自己参考官网文档探索一番。

至此,整个过程介绍完了,当我们在 Cloud Studio 中再次修改文档时,就先提交再推送,这样就把每次修改都同步到了 CODING 的代码仓库,而且可以查看每次提交的版本。值得一提的是,Cloud Studio 还支持多人协作,你甚至可以和其他产品经理一起撰写同一个文档文件。

目前我们正在使用这一套流程来管理产品文档,提高了撰写效率,还可以追溯到每一次修改,同时给其他部门一个连接就可以实时同步产品变更,减少了沟通时间。





您可能也对以下帖子感兴趣

文章有问题?点此查看未经处理的缓存