协会分享:Docs-like-code技术写作
Ray Cheng 英砖生

思路

近期打算在协会开展常态化分享会,首次分享准备以Docs-like-code技术写作为主题,希望能够有一个好的开始,推动协会内部形成相互分享交流的氛围。

分享内容与目标

目前的构思是对整个Docs-like-code这个分支进行梳理,并且保证语言通俗易懂。考虑到大家可能对这一领域尚不熟悉,要尽量从零开始,确保每位参与者都能跟上节奏。分享完了之后,可以组织大家一起尝试选取主题,来进行文档创作,比如

  • 重邮使用指南(国际化流行,校内多了很多留学生,他们对学校的了解比较匮乏,能不能通过这种方式来帮助到他们?当然具体还是要去调研)
  • Trados翻译流程或者使用指南(trados中国社区和论坛不够活跃,相关教程也比较少,我们就尝试写一个trados的文档,在过程中锻炼流程的掌握度)

Docs-like-code简要概括

Docs like code这个技术写作的流程,主要就是围绕git,中心就是:版本控制、快速搭建、团队协作。多人协作的时候,如何来规划,如何依靠每个人来有条不紊的贡献,一点一点的搭建起一个文档网站。对比分享会的想法,其实就是多人协作来分享各自的知识和技巧,搭建起一个知识库。

分享Docs like code这个技术写作分支的目的,同样也有成果可视化的目的,虽然有这本书可以学习,但是对于文档写作这件事情,如何能够向别人证明你会这个流程,你会这些工具,最简单的方法就是把自己写的文档给别人看。但是写文档,要有主题来写,要有项目来给你机会写,要有多人合作来配合写,这也是分享Docs like code的一个目的:有主题、有合作、有机会来写文档。

一下是一些优秀的文档网站:

同时需要向大家强调:

工具和流程能够快速学会,并且在不断使用中加强掌握,但是写作能力(无论是中文还是英文)是真正核心,需要不断锻炼。

分享会主旋律 - 一切从小出发,颗粒度要细

希望将分享会“碎片化” -》 持续化,先通过较短的时长,防止同学们的畏难情绪,先保证分享能够持续开展。暂时草拟了几个主题:

  • PPT制作技巧

    • 某个排版方式、某种技巧能够用于什么类型的文本,比如人物介绍的ppt文本可以用什么技巧,平滑技巧使用方法。
  • 效率工具使用技巧

    • Markdown、GitBook、Notion、英文语法检查工具Grammarly、ocr工具等等的各种使用技巧即可。
  • 技术写作写作技巧

    • 如用户手册、白皮书、产品说明的某种表达方式或者信息组织方法、谷歌的技术写作课某个章节
  • 短视频剪辑

    • 剪映,inshop等软件,技巧包括不限于转场,拼接,配音,视频素材提取,配音,消音。文案脚本
  • 公众号

    • 理论指导知识、带着大家读一篇文章、集中学习
  • 某些翻译技巧或者方法

虽然细,可能每次分享就讲20分钟左右,但是循序渐进,也不会漏洞百出。一步一步的来增加某个知识或技巧的丰富度。用标签标记好每次涉及的技巧或主题,能够将每一次分享会都串联起来。

尝试

这样的常态化分享会形式确实是一次尝试,希望能够通过这种方式,大家一起交流学习。协会也才短短成立一年,多试错总没错。更重要的就是这样形式带来的一点点动力和自由交流的氛围。有问题才是正常的,要不断讨论着完善。
希望能够推动协会的会员们,回去看看自己的收藏夹,找找看过的一些技巧,学一学,来分享一下。

Doc-like-code文档网站构思

目前,选择使用mkdocs这个开源框架,主要考虑到需要在Doc-like-code中介绍markdown,那直接使用markdown的文档框架,可以更好的引入。