java写作教程_如何编写技术教程-发布关于开发人员写作的新书

最新推荐文章于 2024-09-11 18:01:31 发布

culiu9261

最新推荐文章于 2024-09-11 18:01:31 发布

阅读量176

点赞数

文章标签： python java 编程语言人工智能大数据

原文链接：https://scotch.io/tutorials/how-to-write-a-technical-tutorial-announcing-a-new-book-on-writing-for-developers

版权

java写作教程

Writing for Software Developers, a new book by Philip Kiely, teaches you everything that you need to know about creating outstanding technical content. It gives step-by-step guidance on the craft and the business of creating technical tutorials and articles. Writing for Software Developers also features interviews with 11 experts from the community, including Chris on Code, who founded Scotch. In this article, Philip gives you an overview of the process of creating a technical article.

Philip Kiely的新书《为软件开发人员写作》教您创建优秀技术内容所需的一切。它提供了有关创建技术教程和文章的技巧和业务的逐步指导。 为软件开发人员撰写的文章还接受了来自社区的11位专家的采访，其中包括创立Scotch的Chris on Code 。在本文中，Philip概述了创建技术文章的过程。

Writing technical tutorials is a great way to share your skills, earn some money, and generate interest in your project, company, or just your favorite programming language. You do not need to be a famous programmer or a trained writer to create great technical content. Anyone can succeed at writing an outstanding tutorial if they focus on clear explanations of a well-scoped topic for a narrow, defined audience.

编写技术教程是分享技能，赚钱和对项目，公司或只是您最喜欢的编程语言产生兴趣的一种好方法。您无需成为著名的程序员或训练有素的作家就可以创建出色的技术知识。如果每个人都专注于为狭窄且明确的受众群体清晰地解释了范围广泛的主题，那么任何人都可以成功编写出色的教程。

步骤1：您的好主意 ( Step 1: Your Great Idea )

You have a great idea for a technical tutorial, even if you do not know it yet. If you have a topic or title in mind, fantastic!

即使您还不了解技术教程，您也有个不错的主意。如果您有一个主题或标题，那就太好了！

If you do not know what you want to write about, read Chapter 1 of Writing for Software Developers, titled "Finding and Validating Ideas," for free here. The chapter walks you through a proven process for generating strong tutorial ideas.

如果您不知道要写什么，请在此处免费阅读《面向软件开发人员的写作》第1章的标题为“查找和验证想法”。本章将引导您完成一个久经考验的过程，以产生强大的教程思想。

There are two important steps to validate your idea. First, as yourself how much information you can fit in a tutorial. You can get a lot done in two thousand words, a hundred lines of code, and maybe a chart or two. The key issue is appropriately scoping your sample application or topic outline to include only relevant information and assume the right level of background knowledge. Right now, you mostly want to make sure that you are within the right order of magnitude. While some publications offer quick tips, writing about the semantics of a single line of code or short snippet might need expanding. On the opposite end of the spectrum, a topic like "Making a Website in Django" would need to be broken down substantially to extract achievable topics for single articles.

有两个重要步骤可验证您的想法。首先，作为您自己，您可以在教程中容纳多少信息。您可以用两千个单词，一百行代码甚至一两张图表来完成很多工作。关键问题是适当地确定示例应用程序或主题大纲的范围，以仅包括相关信息并假设正确的背景知识水平。现在，您最想确保自己处于正确的数量级。尽管某些出版物提供了快速提示，但可能需要扩展有关单行代码或简短代码段语义的内容。另一方面，诸如“在Django中创建网站”之类的主题需要进行实质性分解，以提取单个文章可实现的主题。

Next, consider your article's audience. What does your ideal reader already know, and why are they coming to your article? These two questions are everything you need to define your audience. Be specific. If you can, model your article's ideal reader off of someone you know from work or school, or at least a role or archetype. Do not be afraid to write for an advanced readership for the right publisher, even if it means your work misses a larger beginner audience. On the flipside, beginner- and intermediate-level articles are often in high demand.

接下来，考虑文章的受众。您理想的读者已经知道什么，为什么他们来您的文章？这两个问题是定义受众所需的一切。请明确点。如果可以，请根据您在工作或学校中认识的人，或者至少是一个角色或原型来为您的文章的理想读者建模。不要害怕为合适的出版商撰写高级读者文章，即使这意味着您的作品错过了更多的初学者。另一方面，初学者和中级水平的文章通常需求量很大。

步骤2：准备代码示例 ( Step 2: Preparing Code Samples )

When I write a tutorial, I walk readers through the process of building some project. While classic examples like ToDo management applications are a fine method to demonstrate some code, I often find that my tutorials are more engaging and better received when I extract code samples from my personal projects or develop more unique example systems. However, having a great application does not guarantee a great tutorial unless you properly extract code samples from it.

当我编写教程时，我会引导读者完成构建某些项目的过程。尽管经典的示例（例如ToDo管理应用程序）是演示某些代码的好方法，但是当我从个人项目中提取代码示例或开发更多独特的示例系统时，我经常发现自己的教程更引人入胜，而且收到的反馈更好。但是，除非您从应用程序中正确提取代码样本，否则拥有出色的应用程序并不能保证它是一个出色的教程。

Code samples are one of the most precise and concise ways to explain technical information. The blessing and the curse of code blocks in articles is that they communicate exactly what the author means to express to the computer, but no more. Thus, sample code is an important component of many technical articles, but it rarely stands alone.

代码样本是解释技术信息的最精确，最简洁的方法之一。文章中代码块的祝福和诅咒是，它们恰好传达了作者要表达给计算机的意思，但仅此而已。因此，示例代码是许多技术文章的重要组成部分，但很少单独使用。

Whenever possible, code should be complete and executable with imports and all other context necessary to allow your reader to copy, paste, and run the code seamlessly. While this context can lengthen code snippets and may eventually feel repetitive, it is the best way to ensure that your reader can access the sample code at any point in the article and use it for their own purposes.

只要有可能，代码就应该是完整的，可执行的，并具有导入和所有其他必要的上下文，以使您的读者无缝地复制，粘贴和运行代码。尽管此上下文可能会延长代码段并最终使您感到重复，但这是确保读者可以在文章中的任何位置访问示例代码并将其用于自己的目的的最佳方法。

The exception is when you are working with large, multi-file projects in frameworks like Django or developing an app for Android or iOS. In these projects, there are dozens of configuration or other files that are full of automatically generated boilerplate. In these cases, use your best judgement in providing sufficient context that the reader can identify where to use the sample code, but do not copy in needless boilerplate. Projects using large frameworks benefit the most from the simultaneous distribution of a repository containing a full, runnable version of the final product that the tutorial constructs.

例外是在Django等框架中处理大型，多文件项目或为Android或iOS开发应用程序时。在这些项目中，有许多配置或其他文件，这些文件或文件充满了自动生成的样板。在这些情况下，请在提供足够的上下文的情况下使用最佳判断，以便读者可以识别在何处使用示例代码，而不必在不必要的样板中进行复制。使用大型框架的项目受益于同时分发包含本教程构建的最终产品的完整，可运行版本的存储库。

For an article, good clean code is concise but easy to understand; you should optimize for readability first. Code golf, or the practice of attempting to solve a solution in the minimum number of characters, has no place in sample code, and neither does pointless verbosity. Your code should follow logical architecture and best practices, but unless you are writing about performance or for an advanced audience, it is better to have code that is fast to read than code that is fast to execute. Finally, lint your sample code before including it in the article lest your readers believe it wrong on the account of IDE warnings.

对于一篇文章来说，好的简洁代码简明扼要，但易于理解。您应该首先针对可读性进行优化。高尔夫代码或尝试以最少的字符数解决问题的方法在示例代码中没有位置，也没有毫无意义的冗长。您的代码应遵循逻辑体系结构和最佳实践，但是除非您是在撰写有关性能的信息或为高级读者而编写，否则最好让代码具有易于阅读的性能，而不是具有易于执行的代码。最后，在将示例代码包括在文章中之前，先对示例代码进行整理，以免读者因IDE警告而认为它是错误的。

第三步：弥合差距 ( Step 3: Bridging the Gaps )

Imagine that you are building a bridge for your readers to cross. On one shore stand your readers, secure in the land of existing knowledge. Your task is to construct a safe passage over a wide strait of uncertainty to the island of new understanding.

想象一下，您正在架起一座桥梁，供读者跨越。您的读者站在岸上，站在现有知识的土地上。您的任务是在不确定的大环境中建立通往新的理解之岛的安全通道。

Now, you cannot simply lay planks for miles and hope that they stay rigid. To cross wide spans, you must construct additional pylons to support the overall structure. Sample code, cited facts, diagrams and images, and other discrete certainties are the pylons spanning the strait. The outline determines the order and distance between these structures. Your job in the article itself is to span each gap with explanation and intuition.

现在，您不能简单地铺设木板数英里，并希望它们保持坚固。要跨越大跨度，必须构造其他的塔架以支撑整体结构。样本代码，引用的事实，图表和图像以及其他离散的确定性是横跨海峡的铁塔。轮廓确定了这些结构之间的顺序和距离。您在本文中所做的工作是通过解释和直觉来填补每个空白。

Each time you sit down to write, focus your attention on one discrete part of your tutorial. With only your outline, research, and relevant code in front of you, write a section in simple, straightforward words. Try not to get hung up on making the language pretty or elaborate, just get the words on the page. It will be much easier to adjust your work when you have a piece to edit.

每次坐下来写作时，请将注意力集中在教程的一个独立部分上。仅在您面前有大纲，研究和相关代码，然后用简单明了的词写一个部分。尽量不要让语言变得漂亮或繁琐，仅将单词放在页面上即可。当您要编辑作品时，调整工作会容易得多。

You know if you are a marathoner or a sprinter, and you can set your writing schedule accordingly. Planning to write a little bit of the article, or one plank of the bridge, at a time will take some of the worry out of writing. Plan your writing time; these writing blocks do not need to be long, twenty to forty-five minutes, but they should be as sacrosanct as any other appointment on your calendar.

您知道自己是马拉松运动员还是短跑运动员，可以相应地设置写作时间表。计划一次写一点文章或桥的一块木板，将消除一些写作上的烦恼。计划您的写作时间；这些书写块不需要很长，二十到四十五分钟，但它们应该与日历中的其他约会一样神圣不可侵犯。