楼仔

V2

2022/04/08阅读:37主题:橙心

如何写好文档,5 分钟带你掌握!

大家好,我是楼仔!

写好文档是一项非常重要的软技能,去年写了近 100 篇文章,积累了一些写文章的技巧和方法,正所谓“熟读唐诗三百首,不会作诗也会吟”,下面我就将这一年多的文档经验,分享给大家。

其实这篇文章本来只发到公司内部,写到一半的时候,码哥(公众号「码哥字节」)突然给我发了一个 文章链接 ,因为该文对于“配图技巧”讲的非常好,所以我近乎照搬这块内容,对于“文章内容”这块,整体思路和部分内容也是参考码哥的文章,特此说明!

这里贴一下码哥的公众号,不是打广告,纯粹表示感谢!

确定主题

很多同学写文章时,文章风格千篇一律。

其实写文章前,你需要明确你的读者群是谁,老板?项目成员?广大用户?面对不同的读者群,你的文章风格会很不一样:

  • 如果你的读者是领导,比如日常的工作汇报,内容需要简明扼要,突出重点,要知道领导都很忙,没时间看些长篇大论的内容;
  • 如果是需求评审,你的读者群是研发和测试,你需要详细讲述每个需求点,尽量不要产生分歧;
  • 如果你的读者是广大用户,你的文章内容必须充实,且浅显易懂,最主要是能让他学有所思、读有所获,你才能吸引更多流量。

所以说,文章落笔之前,先确定你的读者群,文章类型是技术分享、业务实践、团队管理,还是技术理论,不同类型的文章,写作方式也千差万别。

文章标题

如果你的文章需要引起更强的关注度,好的标题非常重要。

比如我之前写公众号,最开始写了一篇敏捷开发的文章,标题为“敏捷开发流程讲解”,结果阅读量只有几十,后来改成“只会用传统开发模式?10 分钟教你玩转敏捷!”,效果就完全不一样。

但如果是需求、方案评审等,啥标题都不重要,因为你的目的不是为了吸引关注度。

文章内容

如果把一篇好的文章比喻成一个美女,那么文章标题、排版、配图都是她漂亮的外衣,这个“美女”是否真的很漂亮,主要看内容。

可能有同学会说,我就高中写过作文,现在除了写项目方案,我都好久没写过文章了,现在让我写,我都不知道怎么下笔,别着急,下面就告诉你方法。

确定写作主题后,我们一定需要先列提纲,我们以这篇文章《只会用传统开发模式?10 分钟教你玩转敏捷!》为例 。这篇文章的主题是敏捷开发,面向的用户群是小米员工,如果上来就告诉大家如何使用敏捷,小白用户可能会蒙圈,因为他可能不知道为什么要用敏捷,有的甚至都不知道什么是敏捷,带着这些问题,你的提纲就很容易列出来:

  1. 什么是敏捷开发?
  2. 为什么要使用敏捷,和传统开发相比,优势是什么?
  3. 敏捷开发讲解,包括基础知识和开发流程。
  4. 敏捷实战,结合具体的实例去讲解敏捷流程、取得的成果,最后加上个人思考和建议。

这个框架就非常清晰了,所以当大家不知道如何写文档,不妨问自己几个问题:

  1. 是什么?
  2. 为什么?
  3. 怎么办?
  4. 这么做以后有啥结果?

有了提纲,就可以开始写了,如果文章内容比较长,建议采用“总-分”结构,让读者能一开始就能 Get 到你要讲的内容,然后再依次展开。

文章写完后,还需要检查错别字、语句不通顺等问题,并对文字进行打磨。我平时每写完一篇文章,都会再修改 3 - 4 遍,最后从头到尾再读一遍,确认没有问题后,才会定终稿。

所以,从现在开始,不会写文章不应该成为你的借口,一起行动起来!

温馨提示:写文章其实也是一个熟能生巧的过程,前期可能会比较困难,你多写几篇,应该就能驾轻就熟。然后,我认为文字功底也非常重要,但是这个并非一朝一夕,我们不要求人人都是鲁迅,但是中国文化博大精深,基本的文学素养,大家还是要有的。

文章排版

文章排版重不重要,我感觉太重要了,你给我一个乱糟糟的排版,我看的心情都没有了,就好比一道菜,看的像一坨,你还有吃的欲望么?

那什么是好的排版呢,我简单列一下:

  • 避免低级错误:我们要避免出现错别字、词语误用、标点符号错误等现象;
  • 首行不用缩进:小时候老师经常教我们首行缩进,但是个人建议不缩进,因为你不是写论文;
  • 段落区分:通过“空一行”来区分段落,并且每个段落的文字不要过长,否则你会发现一堆的文字堆砌在一起,密密麻麻的让人失去继续阅读下去的兴趣;
  • 保留空格:当英文、数字和中文相遇的时候,他们之间要留一个空格,这样阅读起来会更舒适;
  • 专有名词:很多人把 Java 写成 JAVA,MySQL 写成 mysql,会显得你很不专业。

首行缩进和段落区分:

当英文、数字和中文相遇的时候:

比如一些专有名词:

配图技巧

配图技巧,我是直接参考「码哥字节」的文章《写文章搭建框架、排版、画图和配色竟有这么多讲究!》

配图确实是一门学问,我们先看看什么是好的配图:

这些图片都是使用 draw.io 画的,地址:https://app.diagrams.net/

大家觉得画的图不好看,主要原因其实就是两个:

  • 颜色搭配过多:超过三种以上的颜色搭配,色彩的驾驭难度我们把持不住。
  • 采用了过多的高饱和度颜色:高饱和度颜色会比较醒目,但也会造成视觉疲劳,而低饱和度颜色会比较耐看,更适合阅读。

然后就是配色方案(更多配色方案,可以参考码哥的文章),比如:

另外,我认为背景不要设置网格,设置一个低饱和度的颜色即可,这样的配色耐看,也更加沉稳和高级。

主题美化

写好了内容,很多人又会问了,我不是专业编辑,不知道怎么美化文章样式,咋办?

在这里,我推荐大家使用 Markdown 语法来编辑文章内容,作为程序员我们很有必要去了解 Markdown 语法。把你写好的 Markdown 内容粘贴到 https://www.mdnice.com/ 即可完成主题美化。

里面有很多主题可选,我比较喜欢「橙心」这个主题,我的这篇文章也是使用「橙心」效果。

没必要在主题上浪费太多时间,对于我们而言,内容才是最重要的。

分类:

后端

标签:

后端

作者介绍

楼仔
V2