撰写技术博客文章的终极指南

目录

• 关于我如何开始撰写技术博客文章的非常长的介绍
  • 解决你的恐惧
  • 列出你学到的东西
  • 选择你最感兴趣的话题
  • 阅读其他博客文章以获取灵感
  • 确定你的受众
  • 建立大纲
  • 洗澡
  • 进入写作的流程状态
  • 写作有困难？录制你的声音
  • 大声朗读（或使用文本转语音阅读器）
  • 使用数字写作助手
  • 与利益相关者分享您的草稿以收集反馈
  • 添加封面图片
  • 发布
  • 在社交媒体上分享
• 附加资源
• 结论
• 号召行动

关于我如何开始撰写技术博客文章的非常长的介绍

技术技能和内容创作对你的软件开发或（软件开发相关）职业发展同样重要。编程等技术技能可以帮助你完成基础工作，而内容创作则可以巩固你在行业中的领先地位。我承认，并非每个人都有幸在完成日常工作职责和个人责任的同时创作内容，但这是一项值得的投资。创作技术内容可以让你更容易找到工作、获得晋升，并影响行业发展方向，因为它能让招聘经理和其他技术领导者深入了解你的大脑和思维过程。更重要的是，它能帮助你吸收和巩固你所学到的概念。你可能是世界上最聪明、最熟练的软件开发人员，但如果没有人知道你是谁，那么你的机会可能会受到限制。内容创作可以帮助你为自己辩护。这听起来可能有点尴尬，但你可以以一种不尴尬、真实的方式展现自己。像凯尔西·海托尔这样的人，通过以真实而深思熟虑的方式分享自己的想法，从而建立并发展了自己的职业生涯。

我最喜欢的技术内容创作形式是写博客。多亏了妈妈，我从小就对阅读和写作产生了浓厚的兴趣，所以写作一直是我表达自我的首选方式。我有取之不尽的绘本、磁带有声读物、小说、诗歌，以及记录我童年经历的半写笔记本。家里没有暖气的时候，妈妈就会带我和兄弟姐妹去图书馆，所以图书馆成了我的第二个家。免责声明：我并非完美的作家；这只是我喜欢做的事情。

不幸的是，我成年早期就放弃了写作，因为我发现写作很难赚钱，而我当时只有一个目标：赚很多很多的钱。我从小家境贫寒，决心要改善生活质量，于是把所有精力都投入到了一份能赚钱的职业上：软件开发。

几年后，我开始了第三份全职软件开发工作，我的经理 Andy Cunningham 鼓励我把工作中学到的东西写下来。作为冲刺的一部分，我会修复一个 bug 或实现一个新功能，然后写下来。我最早的一篇技术博客文章就是关于如何使用 GitHub Actions 将我们的代码库与 AWS S3 Bucket 同步的。几个月后，我得到了现在的开发倡导者职位，写博客也是我的工作内容之一。

虽然我很高兴能将童年的写作技能与成年后学到的编程技能结合起来，但我也感到有些畏惧。撰写科技文章似乎不像写诗或散文那么容易。写诗时，我拥有所有的创作自由，而写散文时，老师会提供指导。但是，一篇技术博客文章应该是什么样子呢？我曾为以下几个概念而担忧和挣扎：

• 人们会阅读它或者甚至愿意阅读它吗？
• 人们会认为我错了或者愚蠢吗？
• 我有什么有价值的话要说吗？
• 我的博客文章太短了吗？
• 我的博客文章是否太长且难以理解？
• 我想把一切都告诉观众，但我什么时候应该停止写博文呢？

我以前写博客文章没有任何框架或策略。经过一年的技术博客文章写作，并向 Kurt Kemple 等优秀的内容创作者学习，我逐渐形成了一套自己熟悉的策略。在这篇博文中，我将分享我的策略，希望能对你们有所帮助。

解决你的恐惧

技术人员不写作的一个常见原因是他们害怕。

如果你担心自己没有新颖或与众不同的东西可写……
那就提醒自己，不必写任何革命性或创新性的东西，写你所了解的就好。虽然有人可能已经写过类似的主题，但他们的解释方式与你不同。你解释和描述信息的方式会触及到特定的受众，他们学习和消费信息的方式与你相同。

如果你担心自己的写作水平不够……
提醒自己，这是你练习的平台。随着时间的推移，你会进步，而且有时候博客文章不需要华丽的词汇和复杂的句子。有时候，博客文章写得越简单，读者就越容易理解。

如果你担心自己了解得不够……
也许你只懂 HTML，但你比不懂 HTML 的人懂得更多。随着时间的推移，你会不断成长和学习。你不需要等到达到某个水平才开始学习，因为作为技术人员，我们一直在学习。总有一些我们不知道的东西。

如果你害怕犯错……
那就拥抱你的错误吧；它们能帮助你成长。我总是会犯错。有时，我的博客文章会出现语法错误，甚至是技术错误，但有人会纠正我。我从这些错误中吸取教训，并因此成为了更好的作家、教育家和工程师。不要刻意去犯错，但当你犯错时，要知道每个人都会犯错，这是我们走向伟大的旅程的一部分。

如果你担心自己没有时间……
这完全合理，因为我们每个人的责任各不相同，时间也有限。然而，反思你所学到的知识并与世界分享你的知识是一项值得的投资。如果可能的话，和你的经理一起安排定期写作的时间，你的博客文章不必太长。它们可以长或短，由你决定。你拥有对你内容的创作权。

如果你害怕批评……
提醒自己，你是为自己而写。你写作是为了回顾和反思自己的成长。你写作是为了避免反复谷歌搜索或向同事寻求同样的问题帮助。别人的负面评价无关紧要。你可以随时删除他们的评论，或者礼貌地回复，继续生活。我发现，人们在感到受到威胁时喜欢批评别人。

列出你学到的东西

当你在工作中编写代码、完成附带项目或为开源项目做出贡献时，请记录你所学到的东西。

我在 Mac 电脑和 iPhone 上的备忘录应用中保存了一个列表。它看起来像这样：

### Idea list
Hack.Diversity

- How to negotiate salary
- Write thank you letters after interviews
- How to pass the technical interview
- How to learn / navigate a new codebase quickly 
- Tips for passing the CompTIA+ test
- Code
- Invite Automation
- Teaching to Empower: Supporting Early Career Devs
- Generate Social Cards with JavaScript
- From Code to Cloud — Git Emoji
- Build a Blockchain Simulation with JavaScript
- Make better pull requests
- Fuzzy Search Made Easy
- Overcoming the Fear of Contributing to Open Source
- How to Convince Your Boss to Open Source a Project
- Create the Perfect ReadME for your Open Source Project 
Small things I learned with code

- Linked issues
- Fusejs
- How to make a pull request template
- .github/.github/PULL_REQUEST_TEMPLATE.md
- https://github.com/open-sauced/.github/blob/main/.github/PULL_REQUEST_TEMPLATE.md
- .github
- Issue templates
- Forms yaml 
- Being autonomous
- Turning a Checkbox into a circle
- Handling routing with netlify
- Dependencies vs devDependencies
- React functions run on load or after
- Dealing with broken images in React 
- SEQA 
- Rendering components
- Using classList
- Invite automation
- Automatically generate a social image card
- Pull request template forms
GitHub ideas

- Prompt engineering tips with GitHub Copilot
- Lowering barriers with GitHub Codespaces
- Automatically install extensions with GitHub Codespaces
- Automatically install npm dependencies with GitHub Codespaces
- Automatically run your node app with GitHub Codespaces
- GitHub Actions extension
- Using GitHub Pages to federate your Mastodon identity 
- Building a to do list user interface with GitHub Copilot 
- Sending a toot with GitHub Copilot
- P5.js with GitHub Copilot
- I made a GitHub action with my voice
- I used AI to build AI
- How does GitHub Copilot help businesses

如你所见，我的想法涵盖了从简单的概念（例如“用 CSS 将复选框变成圆圈”）到更高级、更有创意的概念（例如“用我的声音构建 GitHub Action”）。有些想法也会重复出现。每当我有一个想法，或者我的经理提到我应该涵盖某个主题时，我都会把它写下来。
列出想法清单很有帮助，这样当你想写作的时候，就不会浪费精力和时间去思考各种主题了。

选择你最感兴趣的话题

值得注意的是，上面列出的很多主题我都没有写过。我只写我目前最热衷的，或者工作中最需要的（因为这就是我的工作）。如果是清单上的想法之一，我就会写。但是，如果我突然灵光一闪，我会立即付诸行动。另一方面，我可能还需要写同事要求写的主题，我会专注于此。我会选择最紧迫或最令人兴奋的主题，因为这能激励我。

另外，请考虑主题的粒度。如果你想写一个通用的主题，比如 React，那么很难写出 React 的每一个概念。要涵盖整个框架，可能需要一本书或一份文档。我建议创建一个 React 的概述，或者选择一个非常细小的主题，例如“理解 useEffect Hook”或“我如何使用 React 搭建博客”。

阅读其他博客文章以获取灵感

写任何东西之前，我都会先阅读。阅读能激发我的：

• 评书
• 我的写作风格
• 我的词汇和句子结构选择
• 我的观点
• 我的写作技巧

通过沉浸在各种文本中，我可以吸收不同的写作风格和技巧，从而调整和尝试自己的写作风格。此外，阅读还能让我接触到不同的思想和视角，拓宽我对世界的理解，并为我的写作提供新的见解。阅读还能帮助我发现需要改进的地方，比如改进句子结构或扩大词汇量。你不必阅读一篇很长的博客文章或小说，但快速阅读一段文字有助于提升我的写作水平。

确定你的受众

现在您已经知道您想写什么，并且有了写作的灵感，接下来就该确定您为谁而写了。

作为人类，我们倾向于为所有人写作。我们想要教导和帮助所有人，这本身并没有错，但我不建议在博客文章中这样做。我经常与一些有内容创作目标的人交流，他们希望同时面向初级工程师、中级工程师和高级工程师。如果你试图覆盖所有人，最终可能会写出一篇没人想读的长文，或者你可能会不堪重负，永远也写不完。相信我；我和其他技术作家都遇到过这种情况。即使我完成了，博客文章的参与度也很低，而且看起来也很杂乱。

即使你选择了一个非常具体的受众群体，其他受众群体仍然会受益。例如，我曾经为初学者写过博客文章，但有时资深工程师会告诉我，他们仍然从博客文章中学到了一些新东西，或者他们很欣赏我分解基础知识的方式。

我通常选择为我自己写作，特别是为过去的我写作。以下是一些例子：

• 当我在编码训练营并且不太了解开源时，我给自己写了博客文章“克服对开源做出贡献的恐惧”。
• 我以 GitHub 开发者倡导者的身份给自己写了一篇名为《如何使用开发容器为 ChatGPT 启用 GitHub Codespaces》的文章，当时我在 GitHub Codespaces 上充当“客户零号（也许是客户 100）”。
• 我给高中时害怕公开演讲的自己写了“当你害怕公开演讲时如何在会议上发言”。
• 在我写技术博客文章之前，我先给自己写了这篇博客文章。

我也写过一些给未来的自己。比如，我经常给开源维护者写建议，但我直到 2023 年才开始维护一个项目。我在 2021 年和 2022 年写的建议对现在的我很有帮助。

建立大纲

现在，是时候规划你的写作内容了。制定大纲有助于你以读者能够理解的方式理清思路。你可以随意调整下面的大纲模板，但这是我用来撰写博客文章的。

“如何做”博客文章的大纲

如果我正在写一篇博客文章，逐步指导人们如何完成一项任务，我会使用如下所示的大纲：

Intro
- Hook
- Problem statement/What this solves for myself or readers

Step-by-Step Guide
1. Step 1
Optional: brief explanation of the step with supporting links for folks to learn more
2. Step 2
Optional: brief explanation of the step with supporting links for folks to learn more   
3. Step 3
...
N. Final Step

Conclusion
- Recap of the process
- Final thoughts or additional tips
- Call to action (e.g., encourage readers to try the steps and share their results/feedback)

查看遵循此大纲的示例：如何使用 GitHub Copilot 发送推文

解释性博客文章的提纲

我将“解释性博客文章”定义为解释某个主题的文章，但它不一定能引导读者完成某项任务。其主要目的是让读者了解某个概念。

Intro
- Hook
- Brief overview of the topic and why care

Body
1. Key Concept 1
    - Definition/explanation
    - Examples 
    - Importance or relevance
2. Key Concept 2
    - Definition/explanation
    - Examples
    - Importance or relevance
3. Key Concept 3
    - Definition/explanation
    - Examples
    - Importance or relevance
...
N. Final Key Concept
    - Definition/explanation
    - Examples
    - Importance or relevance

Conclusion
- Summary of the key concepts
- Closing thoughts or implications
- Call to action (e.g., encourage readers to explore further or ask questions)

以下是遵循此大纲的博客文章示例：人们为什么在容器中进行开发？

思想领导力/观点博客文章的提纲

这类帖子只是我分享我对行业发展方向的看法。很多时候，我会用它来创造富有成效的对话，并分享我的领导才能。

Intro
- Hook
- Brief introduction to the topic/opinion and why it matters to me

Body
1. Supporting Point 1
    - Explanation of the point
    - Supporting evidence or examples
2. Supporting Point 2
    - Explanation of the point
    - Supporting evidence or examples
3. Supporting Point 3
    - Explanation of the point
    - Supporting evidence or examples
...
N. Final Supporting Point
    - Explanation of the point
    - Supporting evidence or examples

Counter arguments (optional)
- Address potential counterarguments or opposing views

Conclusion
- Reinforce the opinion and provide a call to action

以下是一篇遵循此大纲的博客文章示例：开发者倡导对我来说最难的部分

列表博客文章的大纲

这些文章通常以列表形式撰写。这样做的目的是为了让读者能够轻松、快速地理解文章的概念。这类博客文章的标题通常如下：

• 十大秘诀……
• 5 必备品……
• 7 太棒了……

Intro
- Hook or intriguing statement related to the topic
- Brief introduction to the theme or subject of the listicle

Listicle Items
1. List Item 1
    - Explanation 
    - Example
2. List Item 2
    - Explanation 
    - Example
3. List Item 3
    - Explanation
    - Example
...
N. List Item N
    - Explanation
    - Example

Conclusion
- Final thoughts or insights
- Call to action (e.g., encourage readers to share their favorite item or suggest additions to the list)

以下是遵循此大纲的博客文章示例：你不知道可以用 GitHub Copilot 做的 8 件事

洗澡

这个建议可能有点奇怪，但我在淋浴时思考得最好。我觉得流水声能让我集中注意力。淋浴时，我可以在脑海里写出一整篇博客文章。除了淋浴，你还可以尝试其他能刺激思维的活动：

• 步行
• 慢跑
• 听音乐
• 冥想

进入写作的流程状态

排除所有干扰，开始写作。我强烈建议你不要边写边修改。我觉得那样会打乱我的思路。我会按照自己喜欢的顺序填写提纲的每一部分。我说话的方式就是写作，然后就一直写下去。等我把所有想法都写在纸上后，我就会开始修改。

我的编辑过程包括删除不相关的段落、修改拼写错误以及移除不必要的标点符号。我是一个极度轻量级的编辑者。我觉得如果我编辑过多或花费太多时间完善我的博文，我永远都无法发布。在接下来的段落中，我会更详细地阐述我的编辑过程。然而，我的想法是，我希望能够将我的想法分享出去。一旦我分享出去，就会有人联系我——比如我的工作，并要求我提供更完善的版本。然后，我可以利用我的工作提供的资源，比如专业编辑来改进我的博文。
此外，我意识到无论我编辑多少，我的博文总是需要进一步编辑。这就像代码一样——某个地方总有bug。有时，我只是在发布后才进行编辑。通常，人们会给我留言，说我拼错了一个词，我通常会在之后更新。

没什么大不了的。写作是为了完成，而不是为了完美。

写作有困难？录制你的声音

有些人觉得写作很困难，这没关系。布莱恩·道格拉斯告诉我一个技巧，可以帮助那些在纸上写字困难的人：说。录下自己的说话过程，上传到电脑，然后使用一个可以转录这些文字的工具。

我推荐的工具是Descript。它在转录音频方面做得很好。它可能存在一些错误，所以请仔细检查它生成的内容并进行一些小的修改。

大声朗读（或使用文本转语音阅读器）

大声朗读我的写作可以提高我的内容质量。当我阅读自己在脑海中写下的文字时，我可能会注意到一些特定的问题，但大声朗读可以让我：

• 提高清晰度和流动性
• 增强语调和声音
• 发现语法和文体错误
• 评估我的内容的节奏和韵律
• 评估观众吸引力
• 有时，我懒得大声朗读我的文章，或者我很难集中注意力，所以我使用文本转语音阅读器，例如Natural Reader。

使用数字写作助手

像Grammarly这样的数字写作助手可以发现你可能遗漏的错误。Word Tune是另一个我觉得很有用的工具。它很棒，因为它能把我那些难以理解的句子转换成清晰简洁的句子。ChatGPT是另一个工具，但它的争议性更大一些。虽然我不鼓励大家用它来写整篇文章，但它确实能提供很好的反馈。我经常会用以下方式提示 ChatGPT：

• 我在这篇博文中做得好的地方是什么？
• 我在这篇博文中哪些地方做得不够好？
• 您能帮我为这篇博文想一个更好的标题吗？

与利益相关者分享您的草稿以收集反馈

我从 Kurt Kemple 那里得到了这样的建议：把你的博文草稿分享给工作中请你写博文的人（例如产品经理）以及你的目标受众。当我遵循这个建议（因为我比较懒）时，我总能获得很高的参与度和高质量的最终成果。例如，我写了一篇名为“如何解决合并冲突？ ”的博文，并把草稿分享给了我的朋友 Nathan，他最近刚从编程训练营毕业。Nathan 的反馈帮助我确保初学者也能理解我的博文！

添加封面图片

除了精心撰写的内容外，为您的技术博客文章添加封面图片可以显著提升其吸引力和参与度。千万不要忽视这一步。添加封面图片可以展现您致力于以专业且精致的方式呈现技术内容的决心。它表明您为打造一篇视觉上引人入胜且设计精良的文章付出了心血和精力，这可以提升您作为作家和技术专家的信誉。

我不是艺术家，也不擅长设计。我经常使用以下工具来帮助我创作这样的图像：

• Canva
• Figma

我还见过Bekah HW和Brian Douglas等人用Midjourney创作封面。我记得我的朋友 Mayank 也用Excalidraw创作封面。

我的几张封面图片不太可爱，但这里有几张我认为看起来很棒的：

发布

在您选择的平台上发布您的博客文章。您可以使用：

• 开发
• 哈希节点
• 免费代码营
• 中等的
• 或者您的个人网站

您可以根据目标受众以及内容所有权的归属来决定发布地点。我有时会使用BloggU平台在多个平台上进行交叉发布。

在社交媒体上分享

恭喜，您发布了博客，但您还没有完成。与他人分享您的文章有助于文章获得更多参与度。有时，我会收到一些从未见过的人发来的信息，说我的博文对他们很有帮助。社交媒体让我能够接触到世界各地的人们。我尝试在以下平台分享我的博文：

• 叽叽喳喳
• 蓝天
• 乳齿象
• LinkedIn
• 不和谐
• 有时我会在 Slack 上与同事分享帖子（可能会让人感到尴尬，但如果我不告诉他们，没人会知道我创建了这些东西）

我尽量避免以自我为中心地发布信息。如果你想，当然可以，但我希望表明我的意图是分享知识、不断成长，而不是成为关注的焦点。所以我可能会加一小段简介，大致内容如下：“大家好！我以前写博文很吃力，但现在我掌握了窍门，所以我写了一篇博文，希望能帮助其他人也制定一个好的策略。看看吧，告诉我你的想法。”

附加资源

Kurt Kemple撰写的《开发者倡导者内容创作指南》

结论

撰写技术博客内容并非易事，但我希望上述步骤能帮助你保持节奏，创作出引以为豪的内容。再次强调，我们并非追求完美。这个博客本身远非完美，但它做到了两点：
如果我忘记了写作过程，或者感觉自己像个冒名顶替者，我可以随时重读这篇文章来提醒自己；
它能帮助有抱负的技术博客作者提升他们的职业水平。

号召行动

我很乐意听听你有哪些不同的写作策略来提升你的博客内容，或者我列出的任何对你有帮助的建议。想了解更多类似的内容，请关注我！

保持冷静，朋友们😎