食谱风格的技术写作指引
问题
现在搭建一个博客非常容易,但是很少有人关注技术博客应该怎么写。
通常来说,技术博客容易出现以下的问题:
- 内容篇幅太短,没有介绍问题的上下文环境,难以获得共鸣。
- 内容篇幅太长,从头到尾解释每一个细节,没有突出核心问题。
- 维护博客花费大量时间却没有得到相应的反馈,久而久之失去写作动力。
技术博客作为一种写作,是需要指引和练习的。那么是否有一份适合技术博客的写作指引呢?
解决方案
前段时间我了解到一种叫食谱(Recipe)的文章风格,它把文章分为三个部分:问题-解决-讨论。这种风格的技术文章结构比较完整,容易阅读和理解,值得学习。
我把写作指引翻译如下:
-
问题部分:
- 清楚地说明问题。
- 只专注于解决一个问题。
- 帮助读者快速确定这个食谱是否是他们正在寻找的食谱。
- 帮助读者在问题描述中看到自己。
- 以一个问题结束问题部分。这是您的解决方案将回答的问题。
-
解决方案部分:
- 你是读者的向导,与他们同行。使用诸如“我们可以……”和“让我们改变这个……”之类的语言。
- 要有技术性。用代码解释事情很好。
- 使用图表、屏幕截图、动画 GIF 或短视频有助于阐明重点。不要过度使用它们,尽量将它们限制在最重要的点或概念上。对于简短的快速事情,更喜欢 GIF 而非视频。它们会自动播放,制作和嵌入都很简单。
- 图表可以使用像 Excalidraw 这样简单的东西。不需要很精致。
- 假设读者已经熟悉该框架。不是从零开始的。
- 使用简单、清晰的语言。不要不必要地啰嗦。
- 保持代码片段简洁和相关。避免包含与问题或解决方案实际上无关的细节。
- 让读者知道问题何时解决。为他们识别它。
-
讨论部分(可选):
- 在这里您可以对问题和解决方案进行观察和总结。
- 还有其他方法可以用来帮助读者在现实生活中的情况吗?帮助读者看到这一点。
- 这个问题/解决方案是否适用于更大的背景?如果是这样,这是指出这一点的好地方。
以上就是食谱风格的写作指引,本文也是一篇食谱风格的文章。
讨论
经过一段时间的实践,我发现食谱风格很适合技术博客。它能解决了文章上下文描述不清,或者过于纠缠细节的问题,让文章重点聚焦在问题上。另外有了文章框架,写作的时候不是面对一张白纸,心理负担也减轻了不少。
不过写作是自由的,只要能解决问题就是好的技术文章。如果你知道有别的技术写作指引,欢迎在评论区指出,一起提高技术写作水平。