技术文档的撰写

从创意到完美结果的五个步骤 (Five steps to get from idea to polished result)

I’ve been working in the open source community for almost 5 years now, building and promoting developer tools including Meteor and Apollo. In that time, I’ve found that blogging is one of the most effective ways to spread ideas.

我已经在开源社区工作了将近5年，构建和推广包括Meteor和Apollo在内的开发人员工具。 那时，我发现博客是传播想法的最有效方法之一。

A blog post doesn’t take as long to prepare as a video or conference talk, but is easy to consume and can reach a ton of people. I’ve also personally gotten a ton of benefit out of writing: it has helped me organize my thoughts, teach people about technologies I love, and get my name out there.

博客文章的准备时间不需要视频或会议演讲的时间，但它很容易消费，可以吸引大量人。 我个人还从写作中受益匪浅：它帮助我整理了思想，向人们传授了我喜欢的技术，并让我的名字声名远播。

Since publishing my first blog post ever in 2014, I’ve ended up writing 68 posts so far here on Medium, some with over 50k views and 1000 fans, and edited many posts for my friends and coworkers. Over that time, I’ve picked up a few strategies for taking a post from concept to publication.

自2014年发布我的第一篇博客文章以来 ，到目前为止，我到这里为止在Medium上已经撰写了68篇文章 ，其中一些具有超过5万的浏览量和1000个粉丝，并且为我的朋友和同事编辑了许多文章。 在那段时间里，我选择了一些策略，将概念从概念发布到发布。

In this article, we’ll go over five main steps of my process for writing a post:

在本文中，我们将介绍编写帖子的过程中的五个主要步骤：

1. Find a good topic and commit to it找到一个好的话题并致力于
2. Make your goals and audience specific使您的目标和受众特定
3. Have a beginning, middle, and end有一个开始，中间和结尾
4. Get feedback and iterate获取反馈并进行迭代
5. Add finishing touches: packaging, publication, and promotion添加画龙点睛：包装，出版物和促销

Let’s get right into the first step!

让我们进入第一步！

1.找到一个好的话题并致力于 (1. Find a good topic and commit to it)

You can’t get started on a post unless you have something to write about! When I talk to people who want to start blogging, this is often their main blocker.

除非您有什么要写的，否则您不能开始上一篇文章！ 当我与想开始写博客的人交谈时，这通常是他们的主要障碍。

The simplest strategy is to write about what you know. If you spent many hours learning about something, and you think you could explain it in just a few minutes, you’re going to provide a lot of value to your readers.

最简单的策略是写下您所知道的内容。 如果您花了很多时间来学习某些东西，并且您认为可以在短短几分钟内就可以解释清楚，那么您将为读者提供很多价值。

Another idea is to write about an area you think is lacking content. For example, right now there aren’t a lot of posts about how to apply to technical conferences, so content about that could fill a gap in the community.

另一个想法是写一个您认为缺少内容的区域。 例如，目前关于如何申请技术会议的帖子很少，因此有关内容可以填补社区中的空白。

Here are some specific types of posts you could go for. Examples are from the GraphQL-related posts on the Apollo blog:

这是您可以寻求的一些特定类型的帖子。 示例来自Apollo博客上与GraphQL相关的文章：

1. A step-by-step guide to achieving a specific goal: “Building a great scrollable list in React Native with FlatList” or “Simplify your React components with Apollo and Recompose”. These are great for readers that are looking to get in, do a thing, and get out fast.

   实现特定目标的循序渐进指南： “使用FlatList在React Native中构建出色的可滚动列表”或“使用Apollo和 Recompose 简化React组件” 。 这些对于希望进入，执行某件事并快速出站的读者非常有用。

2. An in-depth survey on a particular topic: “Using nullability in GraphQL” or “Anatomy of a GraphQL query”. These are useful if you’re targeting a more interested audience that wants to grab a cup of coffee and learn a ton.

   对特定主题的深入调查： “在GraphQL中使用可空性”或“ GraphQL查询的剖析” 。 如果您要吸引更感兴趣的受众，他们想要喝杯咖啡并学一吨，这些功能将非常有用。

3. A numbered list of useful facts around a common topic: “4 simple ways to call a GraphQL API” or “5 benefits of static GraphQL queries”. These are a fun, lightweight read since you don’t have to commit to reading the whole thing, and it’s easy to consume the bite-sized pieces.

   围绕一个常见主题的有用事实的编号列表： “调用GraphQL API的4种简单方法”或“静态GraphQL查询的5种好处” 。 这些是有趣，轻便的阅读，因为您不必致力于阅读整个内容，而且很容易消耗一口大小的东西。

Now, let me dispel a few common concerns:

现在，让我消除一些常见问题：

1. There is already content out there about this topic. Don’t let that stop you. Even if your idea has been written about before, you can put your own perspective on it, or make it specific to your situation.

   已经有关于该主题的内容。 不要让那阻止你。 即使您的想法以前已经写过，您也可以对它发表自己的看法，也可以根据自己的情况来提出。

2. My idea isn’t interesting enough. A lot of my friends and coworkers don’t end up writing because they are worried their conclusions might be boring or obvious. That’s a normal feeling! If you’re an expert on something, then of course the conclusions you’re writing about will be boring… to you. The key is that people in your audience don’t know that stuff yet.

   我的想法不够有趣。 我的很多朋友和同事都没有写完，因为他们担心他们的结论可能很无聊或显而易见。 那是正常的感觉！ 如果你对某事的专家，那么当然你写的关于将枯燥的结论...... 给你的。 关键是观众中的人还不知道这些东西。

Having said all that, at the end of the day, it’s hard to predict what topics will make a great post and which ones won’t, and often it’s the execution that makes or breaks a post, not a brilliant topic. My main suggestion would be to try writing about several different things and see what works.

说了这么多，到最后，很难预测哪些主题将成为一个好帖子，哪些主题将不会成为一个好帖子，而且往往是执行力决定了一个帖子的成败，而不是一个出色的话题。 我的主要建议是尝试写一些不同的东西，看看有什么用。

2.明确目标和受众 (2. Make your goals and audience specific)

Now that you know your topic, you need an audience and goal for your post. Who will be reading it, and what are they going to get out of it?

既然您知道自己的主题，那么您就需要一个目标对象和目标。 谁来阅读它，他们将从中得到什么？

Your goal needs to be specific so that you can focus all of your energy on one main idea. For this post, the goal couldn’t have just been “write about blogging”. I needed a more specific goal in mind:

您的目标需要具体，以便您将所有精力集中在一个主要想法上。 对于本文，目标不只是“写博客”。 我需要一个更具体的目标：

• Audience: People who want to start blogging, especially about technical topics, but haven’t done it yet.

  受众群体：想要开始写博客，尤其是关于技术主题的博客，但还没有这样做的人。

• Goal: Give people a concrete set of steps and pointers so they can get started.

  目标：给人们一些具体的步骤和指示，以便他们可以开始。

Once you have these, keep your post focused by removing anything that doesn’t contribute, and avoid adding extra detail just because it’s related. I’ve found that relatively concise posts with a 5 - 10 minute read time are the most successful.

掌握了这些内容后，请删除所有无用的内容，以使您的帖子集中注意力，并避免由于相关而增加多余的细节。 我发现，阅读时间为5-10分钟的相对简洁的帖子是最成功的。

Knowing the background of your audience will allow you to tailor your writing to their existing knowledge, and can help determine how you should publish and promote your content. For example, I hope to publish this on freeCodeCamp, because a lot of people in my target audience might already read that publication.

了解受众的背景将使您可以根据他们的现有知识来调整自己的作品，并可以帮助确定如何发布和推广您的内容。 例如，我希望将其发布在freeCodeCamp上，因为目标受众中的很多人可能已经阅读了该出版物。

3.有一个开始，中间和结尾 (3. Have a beginning, middle, and end)

It’s disorienting when a post veers off in a direction you weren’t expecting. Plot twists can be a big benefit in fictional short stories, but it’s easier to consume a technical article if you get exactly what you expect. You can keep your readers on track by giving your post a comfortable structure.

当职位偏离您所期望的方向时，这令人迷惑。 在虚构的短篇小说中，情节转折可能是一个很大的好处，但是，如果您确切地得到了期望的内容，那么阅读技术文章会更容易。 通过给您的帖子一个舒适的结构，您可以使读者保持追踪。

介绍 (Introduction)

The first paragraph or two of your post will either convince the reader to stay on or lose their attention. Start off with a little bit of context to help people understand where your post fits into the big picture. Then, tell your audience what they will get out of reading your article. It might be tempting to leave the big reveal for the end, but watch out: if you don’t have a good hook, your readers won’t stick around to find out.

您文章的第一或第二段将说服读者继续关注或失去注意力。 从一点点背景开始，以帮助人们了解您的帖子适合大局。 然后，告诉听众他们将从阅读您的文章中学到什么。 可能会很想把大展示留到最后，但要当心：如果您没有一个好的钩子，您的读者将不会四处寻找。

中间 (Middle)

Now that you’ve told your readers what to expect, give it to them! Feel free to go into as much detail as you need, and leave sign-posts along the way to orient people. Use a lot of headings, numbered lists, and formatting to help people understand where they are, and enable them to skip around to the content they are most interested in.

既然您已经告诉了读者什么期望，请把它告诉他们！ 随意进入所需的任何细节，并在路途中留出路标以指导人们。 使用大量标题，编号列表和格式来帮助人们了解自己的位置，并使他们能够跳到他们最感兴趣的内容。

结论 (Conclusion)

Don’t just taper off into the void at the end of the article. If your reader has made it all the way there, they really care. Give them a quick summary of what they learned, a pat on the back for reading, and maybe even something to do next if they’re inspired - a call to action.

不要只是在文章结尾处逐渐缩小成空白。 如果您的读者已经做到了这一点，那么他们真的很在乎。 给他们一个简短的摘要，总结他们学到的知识，拍拍一下以阅读，甚至在受到启发的情况下甚至可以做点什么-行动号召。

The format I’m suggesting here isn’t the most creative, and there are certainly other ways of doing it. But a simple structure is the most direct way to communicate with your readers.

我在这里建议的格式不是最具创意的格式，当然还有其他实现方法。 但是，简单的结构是与读者交流的最直接方法。

4.获取反馈并进行迭代 (4. Get feedback and iterate)

You won’t know what people are going to get from your writing until they read it. This is where your assumptions about your topic, goals, the details of the post, and the structure are really put to the test. If you want to have a good result, you can’t skip this step.

您不会知道人们会从您的写作中学到什么，直到他们读完为止。 在这里，您对主题，目标，帖子的详细信息以及结构的假设将真正经受考验。 如果您想获得良好的结果，则不能跳过此步骤。

It might feel like you’re imposing when you ask for feedback, or you might be worried that it will be negative, but people are more willing to help than you expect. It’s much better to find out how your post could be better before you publish it to the world. When I was putting together this post, I got some super valuable feedback that made the content much better and more focused.

当您要求反馈时，您可能会觉得自己很强悍，或者您可能担心这会带来负面影响，但是人们比您期望的更愿意提供帮助。 在将其发布给全世界之前，最好先弄清楚如何更好。 当我整理这篇文章时，我得到了一些非常有价值的反馈，这些反馈使内容变得更好，更集中。

What should you ask your reviewers? My main advice is to leave it as open-ended as possible. Try not to explain up front what you meant to achieve. Hand over the draft as-is, and ask your reviewer what they got out of it or what should be changed. When someone on the Internet comes across your article, they won’t have any extra context and it has to stand on its own.

您应该问您的评论者什么？ 我的主要建议是让它尽可能开放。 尽量不要预先解释您要实现的目标。 按原样移交草稿，并询问您的审稿人他们从草稿中学到了什么或应该进行哪些更改。 当互联网上的某人遇到您的文章时，他们将没有任何额外的上下文，并且必须独立存在。

The main thing to validate from the feedback is: will this post achieve the goals you decided on in step 2? Iterate until you’re confident it will.

从反馈中验证的主要内容是：这篇文章是否可以实现您在第2步中确定的目标？ 迭代直到您确信它会。

5.添加画龙点睛的内容：包装，出版物和促销 (5. Add finishing touches: packaging, publication, and promotion)

Now that you have the idea, the goal, the structure, and some feedback, it’s time to polish everything up and ship it.

现在您有了想法，目标，结构和一些反馈，现在该完善所有内容并将其发布。

打包 (Packaging)

Come up with a great title and subtitle, and make sure your post has at least one image. This is what people will see when the post is shared on Twitter or Facebook, and it’s your chance to get people interested in reading.

提出好标题和副标题，并确保您的帖子至少包含一张图片。 这是在Twitter或Facebook上分享帖子时人们会看到的内容，这是使人们对阅读感兴趣的机会。

It’s also important that your post looks and feels professional, so that your content can really shine. You should aim to have no spelling errors, grammar mistakes, or weird formatting in your post. If you have a friend that is great at spotting small details, ask them to read it over before publishing.

帖子的外观和感觉也很专业也很重要，这样您的内容才能真正发光。 您的目标应该是在帖子中没有拼写错误，语法错误或奇怪的格式。 如果您有一个非常擅长发现小细节的朋友，请要求他们在发布之前仔细阅读。

The freeCodeCamp article about getting published also has some great tips about writing style and formatting. Since you’ve already put so much work into your post, it’s worth it to add that little extra effort to really polish it up and give it a wider reach.

关于发布的freeCodeCamp文章还提供了一些有关编写样式和格式的重要技巧。 由于您已经在帖子中投入了很多工作，因此值得付出一点额外的努力来真正完善它并扩大覆盖范围。

Finally, make sure to credit anyone whose work you referenced, or who helped review and edit your post.

最后，请确保对您引用其工作或帮助审阅和编辑您帖子的任何人表示感谢。

出版物 (Publication)

You’re almost there! Pick where you actually publish the post so that it has the best chance of reaching your audience. Medium is generally a great place for technical content, and makes it easy for people to discover your writing.

您快到了！ 选择您实际发布帖子的位置，以便它有最大的机会吸引您的受众。 中等通常是技术内容的绝佳去处，使人们很容易发现您的作品。

For bonus points, try to get your post into a relevant publication that will help share your content - in this case, I’ve selected freeCodeCamp because I think this advice will be relevant to their readers. If you’d like to do the same, here are their directions for submitting your post. Publications in your areas of interest are likely also looking for posts, so don’t be afraid to get in touch!

为了获得加分，请尝试将您的帖子发布到可以帮助分享您的内容的相关出版物中-在这种情况下，我选择了freeCodeCamp，因为我认为此建议与他们的读者相关。 如果您想这样做，请按照以下指示操作 。 您感兴趣的领域中的出版物也可能正在寻找帖子，因此不要害怕与您取得联系！

晋升 (Promotion)

Once you’ve actually published the post, you’re not done! If you want people to see what you’ve written and get value out of it, make sure to share it in the places where your audience is likely to hang out. This might include Facebook groups, Reddit, Hacker News, LinkedIn, or any other platform. Also, make sure to share your creation on your own social media accounts, like Twitter. Your friends will be excited to read, share, and upvote what you’ve written!

实际发布该帖子后，您还没有完成！ 如果您希望人们看到您写的内容并从中获得价值，请确保在观众可能会闲逛的地方分享它。 这可能包括Facebook组，Reddit，Hacker News，LinkedIn或任何其他平台。 另外，请确保在您自己的社交媒体帐户(例如Twitter)上共享您的创作。 您的朋友会很高兴阅读，分享和赞美您所写的内容！

And now, you’re done. Go get a coffee or take a walk - taking a blog post from start to finish is no small feat. Read any feedback and replies from the the community so that you can keep improving. And when you have another idea, go do it again!

现在，您完成了。 去喝咖啡或散散步-从头到尾写一篇博客文章绝非易事。 阅读社区的任何反馈和反馈，以便您可以不断改进。 如果您有其他想法，请再做一次！

练习无可替代 (There’s no replacement for practice)

We just walked through five of the most important things to do when writing a blog post, from coming up with the idea to publishing. Now that you’ve read it, you try applying this advice and see what works for you.

从提出构想到发布，我们仅完成了撰写博客文章时要做的五个最重要的事情。 现在，您已经阅读了该书，您可以尝试应用此建议并查看对您有用的建议。

I’ll leave you with one last bit of advice. The main thing I learned from blogging over the last 3 years is that I absolutely can’t predict what content will take off and what will end up being a total dud. Sometimes, I’ll put several days into a post, polishing every corner, and it won’t go anywhere. On the other hand, “GraphQL vs. REST”, my most-read post ever, was written in a few hours late at night.

我会给你最后的建议。 在过去的三年中，我从博客中学到的主要知识是，我绝对无法预测什么内容会蓬勃发展，什么最终会变得毫无价值。 有时，我会在帖子中放几天，打磨每个角落，它不会走到任何地方。 另一方面，我读过最多的文章“ GraphQL vs. REST”是在深夜几个小时内写的。

So even if your first, or second, or third posts don’t succeed, keep trying new stuff, putting your ideas out there, and improving over time. The world wants to hear what you’ve got to say. Go tell them!

因此，即使您的第一篇，第二篇或第三篇文章没有成功，也请继续尝试新事物，提出您的想法并不断改进。 全世界都想听听您要说的话。 去告诉他们！

Huge thanks to Anvisha Pai, Angela Zhang, Katie Siegel, and the freeCodeCamp editors for helping review this post.

非常感谢Anvisha Pai ， Angela Zhang ， Katie Siegel和freeCodeCamp编辑人员帮助审阅了这篇文章。

翻译自: https://www.freecodecamp.org/news/how-to-write-a-great-technical-blog-post-414c414b67f6/

技术文档的撰写