食谱风格的技术写作指引

Rei
·

问题

现在搭建一个博客非常容易,但是很少有人关注技术博客应该怎么写。

通常来说,技术博客容易出现以下的问题:

  • 内容篇幅太短,没有介绍问题的上下文环境,难以获得共鸣。
  • 内容篇幅太长,从头到尾解释每一个细节,没有突出核心问题。
  • 维护博客花费大量时间却没有得到相应的反馈,久而久之失去写作动力。

技术博客作为一种写作,是需要指引和练习的。那么是否有一份适合技术博客的写作指引呢?

解决方案

前段时间我了解到一种叫食谱(Recipe)的文章风格,它把文章分为三个部分:问题-解决-讨论。这种风格的技术文章结构比较完整,容易阅读和理解,值得学习。

我把写作指引翻译如下:

  • 问题部分:
    • 清楚地说明问题。
    • 只专注于解决一个问题。
    • 帮助读者快速确定这个食谱是否是他们正在寻找的食谱。
    • 帮助读者在问题描述中看到自己。
    • 以一个问题结束问题部分。这是您的解决方案将回答的问题。
  • 解决方案部分:
    • 你是读者的向导,与他们同行。使用诸如“我们可以……”和“让我们改变这个……”之类的语言。
    • 要有技术性。用代码解释事情很好。
    • 使用图表、屏幕截图、动画 GIF 或短视频有助于阐明重点。不要过度使用它们,尽量将它们限制在最重要的点或概念上。对于简短的快速事情,更喜欢 GIF 而非视频。它们会自动播放,制作和嵌入都很简单。
      • 图表可以使用像 Excalidraw 这样简单的东西。不需要很精致。
    • 假设读者已经熟悉该框架。不是从零开始的。
    • 使用简单、清晰的语言。不要不必要地啰嗦。
    • 保持代码片段简洁和相关。避免包含与问题或解决方案实际上无关的细节。
    • 让读者知道问题何时解决。为他们识别它。
  • 讨论部分(可选):
    • 在这里您可以对问题和解决方案进行观察和总结。
    • 还有其他方法可以用来帮助读者在现实生活中的情况吗?帮助读者看到这一点。
    • 这个问题/解决方案是否适用于更大的背景?如果是这样,这是指出这一点的好地方。

出处:Recipe Style Guide

以上就是食谱风格的写作指引,本文也是一篇食谱风格的文章。

讨论

经过一段时间的实践,我发现食谱风格很适合技术博客。它能解决了文章上下文描述不清,或者过于纠缠细节的问题,让文章重点聚焦在问题上。另外有了文章框架,写作的时候不是面对一张白纸,心理负担也减轻了不少。

不过写作是自由的,只要能解决问题就是好的技术文章。如果你知道有别的技术写作指引,欢迎在评论区指出,一起提高技术写作水平。

评论
社区准则 博客 联系 反馈 状态
主题