前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
圈层
工具
发布
首页
学习
活动
专区
圈层
工具
MCP广场
社区首页 >专栏 >如何写一篇产品文档

如何写一篇产品文档

原创
作者头像
研究僧
修改于 2020-06-11 03:44:37
修改于 2020-06-11 03:44:37
1.9K06
代码可运行
举报
运行总次数:6
代码可运行

开篇

笔者有着多年的toC开发、运维开发和运维工作经验,也曾开发很多内部运营系统,更多是从功能角度出发满足业务运维的需求很少提供完整规范的产品文档,关于开发的运营系统使用方法更多是通过口口相传,听起来不是很正规但确实是这样走过来的。

笔者也反观公司内部的运营系统也会出现笔者遇到的情况,或者是提供了基本的文档但随着时间的推移文档年久失修,甚至出现问题联系文档里的负责人已经离职的囧境。

两年前笔者开始从事toB业务明显感觉到与toC业务的不同,相应的产品要有配套的文档和说明书且产品文档要优先于版本迭代,最起码也需要同步于产品迭代功能发出。

ToB面向企业级别用户文档是一个必不可缺的产物,但用心整理的产品文档并提供用户也会遇到一些问题,譬如产品运营的过程中我们经常与用户交集的Helper(在线服务客服)会比较困扰因为用户没有看文档的习惯更喜欢直接来问Helper,所以有时也在思考是否要投入更多的经历来完善文档? 为什么用户不看文档?我们的产品是否出现了什么问题?很多的问号盘旋在脑海中。但思考过后最终的答案还是非常肯定的文档是产品非常重要的一个环节,用户可以不看但我们一定要提供并且精心的维护它。下面就通过一个真实的案例ULS产品文档开发过程,来介绍如何写一篇产品文档,以下是ULS产品文档目录结构。


ULS产品背景介绍

ULS(Unified Log System) 统一日志服务,是内部的一套开发上报日志、存储和最终消费一站式平台。 此产品是在2018年底开始由我们部门负责,从ULS代码注释中可以看到它大概7年前(2012)开发的是一个有历史的内部日志系统同时有一批忠实的用户。

竞品文档结构调研

ULS产品是一款有历史的内部系统经过了多年的发展,文档散落在各处另外很多文档也年久失修有很多的错误,我们优先整理了旧文档列表并验证旧文档没有问题后,统一放到现有系统显眼位置让用户第一时间可以看到。接着我们对日志服务竞品的文档结构做了一些调研,这些产品包括腾讯云、A云和QN云,竞品目录结构对比可以访问( https://docs.qq.com/sheet/DTkZRSGZORkZvdHZq?opendocxfrom=admin&preview_token=&coord=K15A0A0&tab=BB08J2 )。

经过竞品调研并结合我们当前的实际情况,最终我们的文档结构一级目录为,版本更新历史、快速上手、5分钟视频介绍、产品介绍和FAQ问题整理等。 有了文档结构后在此基础上我们将老的文档中一些信息进行整理并灌入新文档系统中,这里强调一下我们使用的是GitBook来管理我们文档,有很多内部系统依然使用Word文档来管理,笔者觉得更加推荐GitBook它有版本管理功能,在并行开发文档过程中避免出现错误与覆盖的情况,同时可以对比不同版本间的差异方便我们优化文档,最主要他呈现给所有人是一个WEB网站,信息更新也更加的实时。

寻找用户群体

个人觉得做产品最重要一个环节是用户群体,只有了解用户群体我们在产品迭代过程中的取舍才会有依据。这里举个比较形象的列子也是笔者之前一直在思考的问题,为什么Windows系统有回收站而Linux系统没有回收站?后者的答案笔者在《Unix编程艺术》找到,这句话来自书的原文——Linux世袭了Unix的设计理念与传统,而Unix本身并没有这样的设计并延续到了Linux。Unix面向更加专业的用户 ,Unix的开发者喜欢清晰、简单的操作,用户告诉做什么就做什么,即便用户使用的命令等价于“向我开枪”的命令。而这样做Unix的开发本能辩解的就是:保护用户避免自我损害,应该是GUI或应用程序级别的事,而非操作系统。 所以可以很清楚的看Linux的用户群体更加的专业,Windows系统正好反过来,如果用相机比喻的话Windows更像傻瓜相机,Linux是一个专业的数码相机彼此之间有自己针对的用户群体。

我们对日志竞品产品调研也再次验证了这个结果,这里包括QN云智能日志平台 、A云日志服务和日志易等业界日志产品做了深入的调研并与ULS进行对比发现不同的产品在功能上是有取舍和针对性的(竞品调研报告:https://docs.qq.com/sheet/DTkdtREdPU2dES2ZG?preview_token=&coord=B4A0A0&tab=BB08J2),从产品功能上来反推用户画像:

A云:用户群体需要具备更强的开发能力,而其系统更多像一个脚手架与A云产品相互打通,用户具备开发能力通过脚手架可以实现常用功能外的一些定制化开发需求。

QN云:用户人群需要有计算机的背景但并非一定需要较强开发能力,该产品提供了丰富的功能和强大的用户WEB界面,基本可以满足常见用户的80%需求场景。

某易:功能和文档十分不完整,从日志易的立足行业(金融、能源、运营商)看到,日志易有为不同行业提供不同的解决方案。用户画像:需要个性化定制日志服务的企业。

ULS(内部系统):目前内部运营了7年多有一定的铁杆粉丝量,所以ULS用户画像就是内部的开发,这些开发主要集中在CSIG、PCG和少量的IEG等,这也能看到我们系统用户的属性。

详细调研报告可以参考:( https://docs.qq.com/sheet/DTlNZZE1FQ3hxc3NW?opendocxfrom=admin&preview_token=&coord=A4A0A0&tab=BB08J2 )

有了用户群体后我们在写文档时就有了依据,譬如笔者在文档中写过ELK有同学会挑战需要介绍ELK是什么, 但我们的产品用户群体是开发,他们会具备一定的知识基础,依据这背景笔者是不会在文档中写过多的ELK介绍的。

文档正确性校对

在刚开始的时候我们从能收集到的历史文档中搬了很多东西到新创建的文档系统。这些文档多由老的日志系统开发撰写,在实际操作过程中我们发现安装文档执行并非100%执行成功或者说文档只写了在安装过程中最好的情况下是什么样的,我们通过多位测试同学不断的对文档验证与校对,并对文档中的内容进行重新排序与分类最终达到我们预期的效果。 这里有一个值得分享的案例,譬如我在安装日志服务的Agent,其实我们直接通过运营系统下发就可以了但我们运行的服务器环境在文档上并没有明确操作系统发行版本是什么,kernel版本号,是否经过初始化系统等。 笔者通过验证文档安装的服务器每次都会执行成功,而测试同学每次测试都失败,其实主要原因就是我们使用的服务器初始化系统不一样导致系统上缺少依赖包,测试同学在安装Agent时就会报错,这些细节都是通过一步步测试后发现并整理到文档中的。 而我们的文档在迭代过程中一定需要经过测试同学进行严格的流程测试才能保证它的正确性,最终提供给用户也是靠谱的手册。

一定要有的CHANGELOG

在产品开发过程中一定要通过版本来迭代需求。 以ULS为例,我们有自己的用户群体,在用户群里中又建立了产品相关的社区,通过社区的反馈不断收集用户的意见,根据用户的意见在每次版本迭代中进行优先优化,每一个版本我们都能看清楚他的优化点与用户关心的问题,每次迭代一个版本并对比版本之间的变化会发现你的产品会更上一个台阶,我想这也是做好一个产品的方法之一。

不能没有的FAQ

开篇我们说过其实最头痛的是提供了用户文档用户不去看,我想这也是很多人的用户习惯,如果文档与Helper都在的情况下,很多人会优先询问Helper。其实在接Uls产品的时候我们就建立了这里处理问题的流程见以下截图,我们有1线,2线(uls_helper)和研发,收集用户每一个信息并统计分析整理有共性的问题录入文档的FAQ中。有了流程的保障会发现FAQ整理的问题慢慢的增多,随着时间的推移用户可以社区内发出问题,并由其他用户以文档的形势进行内部闭环,释放产品的人力投入,形成良性的需求与供给,所以在文档中的FAQ是非常重要的一个环节。

文档中视频演示的重要性

对比日志竞品文档提供视频演示并不多,但是在运营日志产品的过程中发现了用户的习惯,这里再一次强调就是很多用户不习惯看文档,所以我们也尝试通过视频演示方式是否更好。在准备视频演示的过程中也发视频演示和产品文档是相辅相成的事,从最开始录制视频大约需要7分钟逐步优化文档结构和安装程序到最终将整个时间控制在3分钟左右,这也体现了准备视频演示对文档建设的推动作用。

最后,笔者觉得一个好的产品要尽量让用户少看文档,印象中看过一个文章说Iphone的开机按钮连不到一岁的小朋友知道去按并开机。希望每个人都是一个好的产品经理并作出更优秀的产品。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

评论
登录后参与评论
暂无评论
推荐阅读
编辑精选文章
换一批
利用腾讯视频存储视频
今天发现腾讯视频除会员外的1080P分辨率的会员视频加了防盗链会返回403,其他的都没有加防盗链,在视频里右键可以在调试视频里看到视频的外链,也可以用一个简单的html页面来获取腾讯视频播放地址,哈哈,虽然上传文件要审核,但也是可以存很多好东西嘛。
qiangzai
2021/12/21
7.8K1
利用腾讯视频存储视频
文章生成海报没有图片的问题
因为我图片一般都是在文章中上传存在本地服务器,但是文章中的图片引用我都是存在oss并且用腾讯的cdn静态加速了,就出现的了文章生成海报没有图片的问题,原因就是跨域导致的,什么是跨域呢?我之前记得腾讯cdn可以在 HTTP header 设置跨域问题,现在改名为 Response Header ,操作一样,但是我设置完还是不行,自己问了问亲爱的老家伙 @叶开桑 ,原来要刷新预热,淘汰cdn节点上的旧文件,重新获取文件的新版本,这样就可以了,简单记录一下。
qiangzai
2021/12/21
5280
文章生成海报没有图片的问题
Typecho关闭无用输出
在Typecho主题的头信息默认一般会输出很多无用的信息,而且很多现在也用不到,听都没听说过,输出乱七八糟的不好看,功能还占用服务器资源,所以直接关闭了得了。
qiangzai
2021/12/21
6840
Typecho关闭无用输出
网站设置彩色图标(通用)
目前大多数博客网站图标都是使用Font Awesome图标库里的图标,本站刚开始也使用了原生的图标,很多网站里面都集成了Font Awesome,使用奥森图标有很多优点,用图标代替图片,加载快,使用灵活。
qiangzai
2021/12/21
1.3K0
网站设置彩色图标(通用)
最新pycharm不能自动补全且路径中\变成¥的解决方法
今天晚上更新了最新的pycharm,刚打开就出现一个bug,不能自动补全代码,我还以为是我设置问题,仔细看项目路径中\也变成¥,让人头疼,出现的问题如下图
qiangzai
2021/12/21
1.2K0
最新pycharm不能自动补全且路径中\变成¥的解决方法
jsDelivr存储视频.m3u8
对于博客来说,媒体资源的存取方式至关重要,作为资深的老白嫖怪,借助Jsdelivr加速Github上存储的图片已经是公认的方案,但对于视频来说,面对动辄几百兆的视频资源,你几乎无法找到一个免费的“视频床”,在第三方直接防盗链能力日渐完善的当下,急切需要一种折中方案。本文就借鉴前辈的尝试,将视频存放在Github之上并利用Jsdelivr实现加速,并利用DPlayer将其插入到自己的博客中,大多数影视站就是这么淦的,所以咱也来试试。
qiangzai
2021/12/21
2.3K0
jsDelivr存储视频.m3u8
解锁宝塔网站相关付费插件
bt相比各位都知道,不多介绍了,网上也有很多专业版什么开心版,也是可以免费使用付费插件,相比之下还是有安全隐患,那么,下面我们可以不用那些直接动手修改py代码自己操作实现免费白嫖付费插件。
qiangzai
2021/12/21
8320
解锁宝塔网站相关付费插件
恢复Chrome https协议和子域名显示
在谷歌升级到Chrome 8之后子域名不显示,这里借助谷歌商店的插件进行实现www子域名,跟https协议显示,由于此插件用于GSB(Google Safe Browsing)的恶意站点提交,所以插件源码中包含了禁止隐藏协议名和www子域名的规则。
qiangzai
2021/12/21
1K0
恢复Chrome https协议和子域名显示
唯美动态404网页
超可爱的唯美动态404单页,图片我已上传至仓库并使用jsDelivr CDN加速,各位不用担心,好看各位自取吧 (我已经换了)
qiangzai
2021/12/21
6550
唯美动态404网页
国庆中秋特效头像生成
超火的国庆节国旗头像生成源码,依据去年腾讯新闻活动修改,别人增加了中秋节头像,静态页前端生成速度超快,我本人在一些软件中,强仔通过拆包一些类似的软件,又把几种软件上的特效添加到网页中,这样一来原有的5种基础特效上又加了10种特效,快来下载体验吧。
qiangzai
2021/12/21
2660
国庆中秋特效头像生成
离开和进入html页面时改变title
离开和进入页面时改变网页标题,最近也才刚刚开始js学习,下面这段代码简单就是说访客如果离开你的网站之后,站点标题会发生变化。原理是使用了HTML5的Page Visibility API 目前页面可见性API有两个属性,一个事件:
qiangzai
2021/12/21
2.2K0
离开和进入html页面时改变title
vConsole 让你在手机上也能轻松调试网页
vConsole相信各位并不陌生,它是一个轻量、可拓展、针对手机网页的前端开发者调试面板。有时候为了想在手机上对网页进行 Debug,可手机上没有F12,电脑却又不在身边,请不要着急, 这时就需要vConsole了, vConsole是腾讯推出的一个轻量、可拓展、针对手机网页的前端开发者调试面板,正好解决了这一痛点!
qiangzai
2021/12/21
2.1K0
vConsole 让你在手机上也能轻松调试网页
deepin深度系统安装
说起来也是的悲伤的故事,上学期的linux差一分还是挂科了,老师也是够绝情,一分也不多给,没办法,最近也是忙着复习linux考试,这不,发现了deepin深度操作系统,第一眼看着感觉好漂亮,虽然是基于liunx开发的,但是界面还是和win很像,而且比win美观,我就想体验一波,第一次发现内存给少了,这边重新安装简单记录一下安装过程。
qiangzai
2021/12/21
1.5K0
deepin深度系统安装
iconfont的几种引用方式
说起阿里的iconfont,肯定都用过FontAwesome,相比之下,二者都是免费的图标,引用方式大差不差。从兼容性的方面来讲,iconfont支持所有低版本浏览器,而FontAwesome只支持IE7+的高版本浏览器,从图标美感和数量方面来讲,这都不用比,显然iconfont更胜一筹,从使用上讲,iconfont也更为灵活,不像FontAwesome那样,需要引入整个文件包里的文件到项目,显得臃肿,FontAwesome有文档支持,而iconfont在下载添加图标时会有一个demo文件供参考,也是一个不错的参考方法。
qiangzai
2021/12/21
1.1K0
iconfont的几种引用方式
Typecho实现简单独立页面跳转
博客友链是一个网站必不可少的一部分,简单的 a 标签跳转外链早已不够新颖,很多网站也引入了独立的跳转页,这样能更好的给访客留下深刻印象,其中引用的技术只是一段简单的js代码
qiangzai
2021/12/21
2.2K0
Typecho实现简单独立页面跳转
Typecho实现文章上一篇下一篇功能
在别人博客看到主题底部都带上一篇下一篇的跳转功能,注意到这一细节后才想到自己的博客主题没有带,夺笋啊这
qiangzai
2021/12/21
7040
Typecho实现文章上一篇下一篇功能
Gravatar镜像源自建教程,使用CDN加速无需配置反代
Gravatar相必大家都知道,“全球通用头像”这么一款服务,如果在Gravatar的服务器上放置了你自己的头像,那么在任何支持Gravatar的博客或留言本上留言时,只要提供你与这个头像关联的Email地址,就能够显示出你的Gravatar头像,十分的方便。但因为网络环境原因,Gravatar官方提供的服务在国内访问时体验较差,很多域名速度拉跨,时常存在无法访问的情况,国内也有不少组织提供了免费的头像镜像服务,下面有一些国内常用的 Gravatar 镜像源和修改方法:
qiangzai
2021/12/21
2.8K0
Gravatar镜像源自建教程,使用CDN加速无需配置反代
Typecho评论头像隐藏QQ号
因为腾讯留的头像接口有很多,大部分都是需要传入QQ参数,例如:http//q.qlogo.cn/g?b=qq&nk=qq&s=100这个接口,需要跟QQ参数才能显示QQ头像,这样会暴露用户隐私 那
qiangzai
2021/12/21
1K0
Typecho评论头像隐藏QQ号
网站那些阻止F12所遗留的彩蛋
看到好看的网页或者样式时候,大家都会利用我们浏览器的F12,也就是开发人员调试利器这一功能,那么各位老表为了防止自己心爱的代码被偷,也是煞费苦心,给网站设置各种键码限制,网站上也就遗留了很多彩蛋,这也也是一个独特的风景,下面一同欣赏几款我见到过有趣的彩蛋吧。
qiangzai
2021/12/21
5010
网站那些阻止F12所遗留的彩蛋
twitter主题实现前台发文章
博客原来主题是仿推特的一款主题,文章样式特别多,所以咱也是特别喜欢,也总喜欢搞来搞去的,今晚也是从 @XiaoFans 那里发现了新东西,实现主题前台的发文,前台发文挺新颖的,也是特别想动手实现一下,前台发文是博客的一大特点,可以更加方便,目前只能实现发送文章,后期 @XiaoFans 会加更多功能,上传图片和表情之类的,其他主题原理一样,过程适用于typecho博客,一起来学习下吧
qiangzai
2021/12/21
6850
twitter主题实现前台发文章
相关推荐
利用腾讯视频存储视频
更多 >
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档
本文部分代码块支持一键运行,欢迎体验
本文部分代码块支持一键运行,欢迎体验