撰写文章
I edit a lot of technical articles over at Smashing Magazine, and write a good few myself. Over the years I’ve absorbed a lot of information in terms of what works when writing tutorial content, and one thing I keep coming back to is that you need to know who the ideal reader of your piece is.
我编辑了很多了，在碎杂志的技术文章， 并写了好几个我自己 。 多年来，我就撰写教程内容时的工作方式吸收了很多信息，而我不断回想的一件事是， 您需要知道谁是您文章的理想读者 。
Technical articles can’t all start from explaining to the reader how to create an HTML page, therefore they all bring with them some assumed knowledge. The level of assumed knowledge might be basic HTML, or for an advanced piece might involve a whole compendium of languages and tools. There is always something you expect your reader to know. Define that for yourself before you start.
技术文章并非全部从向读者解释如何创建HTML页面开始，因此它们都带来了一些假定的知识。 假定的知识水平可能是基本HTML，或者高级知识可能涉及语言和工具的完整纲要。 您总希望您的读者知道一些事情。 在开始之前，请自己定义。
- What languages does the reader need to know, and to what level?
- What tools, frameworks or libraries should they be familiar with?
- 读者需要了解什么语言，以及达到什么水平？
- 他们应该熟悉哪些工具，框架或库？
Once you have that list, you can refer back to it as you write the article. You may even be able to think of someone you know who is that ideal reader. As you come to explain something, which refers to one of the things you expect the reader to know, you don’t need to over explain. If the thing you need to refer to isn’t in that list, then give a more complete explanation, perhaps linking to another article for more detail. Your list helps you to explain the things that need explaining, and avoid filling the article with things your reader should already know.
获得该列表后，您可以在撰写本文时参考它。 您甚至可以想到一个您认识的人，是那个理想的读者。 当您开始解释某些东西时，它指的是您希望读者知道的一件事，您无需过度解释。 如果您需要参考的内容不在该列表中，请给出更完整的说明，也许可以链接到另一篇文章以获取更多详细信息。 您的清单可以帮助您解释需要解释的内容，并避免在文章中添加读者应该已经知道的内容。
Your list should also be part of your introduction to the article, explain to the reader that to follow along they need to already know certain things. You could always offer a link to an introduction to those subjects. If the article is for real beginners, then be clear about that too, it’s helpful to know right away that something has been written for a person like you.
您的清单也应该是本文介绍的一部分 ，并向读者解释说，跟随他们必须已经知道某些事情。 您总是可以提供指向这些主题的简介的链接。 如果该文章是针对真正的初学者的，那么也要弄清楚这一点，立即了解为您这样的人写的东西会很有帮助。
为有经验的人写作 (Writing for the experienced)
When writing for experienced practitioners, you need to write something that offers value over that person just looking at the documentation. Your list of assumptions, and imagining your ideal reader can help here. An experienced person is likely to be able to get to “Hello, world” from the product docs. Therefore an article for that person needs to share more than an introduction. Good things to include are tips and tricks gained from your own practical use, the sort of thing you don’t get from the docs but from actually using the tool within the constraints of a real project. The docs often don’t go into how the tool can be combined with other tools or techniques, how it can fit into an existing workflow, or how you can transition from an older way of doing things to this new fancy way. All of these are good topics for the more experienced reader.
在为有经验的从业人员撰写文章时，您只需要阅读文档，就需要编写一些比该人有价值的东西。 您的假设清单以及想像理想的读者可以在这里提供帮助。 有经验的人很可能能够从产品文档中获得“世界您好”的信息。 因此，给该人的一篇文章需要分享的不仅仅是介绍。 要包括的好东西是从您自己的实际使用中获得的提示和技巧，不是您从文档中获得的东西，而是您在实际项目的约束范围内实际使用该工具所获得的东西。 文档通常不会讨论该工具如何与其他工具或技术结合，如何适应现有工作流程，或者如何从旧的做事方式过渡到这种新的幻想方式。 对于经验丰富的读者来说，所有这些都是不错的话题。
为初学者写作 (Writing for the beginner)
When writing for beginners to a technology, be especially careful with your assumptions when considering your ideal reader. It’s incredibly offputting if you think something is for beginners and then realise you need to understand an entire toolchain just to get started. Avoid using words like “just” and “simply”, include good resources for getting started with any prerequisites.
为初学者编写技术书时，在考虑理想的读者时要格外小心。 如果您认为某些东西适合初学者，然后意识到您需要了解整个工具链才能上手，那将令人难以置信。 避免使用诸如“ just”和“ simply”之类的词语，并包括良好的资源以帮助您入门。
However remember that many readers will be beginners to this technology but not beginner developers. A great example is when writing about the modern JavaScript ecosystem. A reader might be a perfectly competent JavaScript developer, but they have never used a framework like React. They don’t want to read something that speaks to them as if they have never written JavaScript before, but they will need a lot of background information about how the ecosystem now works to be able to start to work with React. As a writer, it is a useful practice to keep a list of really great introductory articles to various subjects. You can then use those as links to help people with the things you don’t have time to cover in your piece.
但是请记住，许多读者将是该技术的初学者，而不是初学者。 一个很好的例子是关于现代JavaScript生态系统的文章。 读者可能是完全有能力JavaScript开发人员，但他们从未使用过像React这样的框架。 他们不想像以前从未编写过JavaScript那样阅读对他们说话的东西，但是他们需要大量有关生态系统现在如何工作的背景信息，以便能够开始与React一起工作。 作为作家， 保留各种主题的出色入门文章的列表是一种有用的做法 。 然后，您可以将这些链接用作链接，以帮助人们处理您没有时间覆盖的内容。
So, next time you start writing, or creating a presentation, or tutorial video, first consider the question who is this for? Answering that will make all the difference.
因此，下次您开始写作，创建演示文稿或教程视频时，请首先考虑以下问题： 谁是谁？ 回答将有所作为。
撰写文章
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
