文档 – 第2页小小书 XXshu

撰写下一篇技术文章的5个步骤

在过去的几个月中，我写了很多技术文章。一开始，将我在英语课上学到的东西应用到编程和计算机的冷逻辑上是不自然的。尽管如此，我冲洗并重复了足够的时间才发现它毕竟不是那么糟糕。下面，我每次撰写技术性文章时，都会以一种或另一种形式概述我采取的五个步骤。在撰写文章时，您将扮演老师的角色。这样一来，您将体验到最高级的学习形式，并且可能会发现至少一件事关于您所写的东西，而您以前从未知道过。在成为老师之前，无论那件事可能是什么，您都必须做这件事。我想起了艾默生经常引用的话： “做某事，您将拥有力量。” 拉尔夫·沃尔多·爱默生不管您的教程或主题需要什么，请务必按照自己的节奏来体验整个过程，从头开始完成。如果没有分步进行的过程，那么现在是时候寻找有关概念的问题的答案，甚至可以提出以前可能没有想到的新问题。您的听众会遇到的问题比您一次开会想想的要多，但您可以尽最大努力解决大多数问题！在执行此过程时，请注意。每次单击按钮，每次提示，键入的所有内容-都写下来。当您试图准确地重构其他人的消费所发生的情况时，您将不想再钻研研究阶段所需的详细程度。…

技术写作第二部分：技术写作与文案写作

你可以用很多方法写在最近的讨论中，提出了技术写作和文案写作的主题。乍一看，这两个学科似乎很不同，但最终目标却是相同的：使读者满意。技术作家以有用而简洁的文档满足了客户的需求。撰稿人为他们的用户提供了写得很好且有趣的文章。相似之处如上所述，两个写作学科的主要目标是相同的。在经历了作者的工作之后，无论期望如何，读者都不会觉得自己在浪费时间。这两个领域都强调写得好，避免错误以及进行深入研究。您不想散布错误信息，尤其是在这些不确定的时期。您也不想别人反驳您的文章或指南存在重大不一致或错误之处。他们还采用更严格或更宽松的风格指南。写作的连贯性很重要，以免使读者感到困惑。而且，无论在哪个领域，都应强制执行拼写，语法和其他规则。附加材料对于这两个学科都可能非常有用。一张图像，不管它是怎么写的，都值一千个单词。图表甚至视频也可以增强文章或指南的功能，因为并非每个读者都能够理解用语言传达的内容。差异…

记录您的编码经验的艺术

这个周末，我做了两件事：我遍历了服务器和GitHub帐户上的旧个人项目，我尝试了新的React.lazy和React.Suspense功能。我为什么要告诉你呢？因为这两个事件混合在一起，使我有了一个主意，以便在我为我测试一些新东西时找到一种适当的方式来记录我的过程：技术，编码语言或库功能。我所说的编码经验当您想尝试新的“东西”时，假设是：您知道这种“东西”是什么（例如，一种新的编码语言），您对应用程序有一个小想法，可以测试这个新的“东西”（例如，很棒的播客列表）。我决定将这两点的混合称为实验。阅读我的旧个人项目自述文件使我意识到，除了“…

如果技术作家失踪了怎么办

在此博客中，我们多次提到，许多人对技术作家的工作一无所知。老实说，文档团队可能被低估，甚至被低薪。当然，整个技术交流者团体正在尽最大努力使全世界了解他们的专业，他们在生产和支持过程中的重要作用。但是，技术写作的作用真的那么重要吗？为了共同解决这个问题，我们决定邀请您与我们一起玩一些“假设”游戏。如果所有技术作家一天都消失了怎么办。不用说一句话或留下任何音符就进行“吹气”。会发生什么事？终端用户想象一下，购买一台新设备，例如咖啡机或吸尘器。并且，它没有用户手册。或者，它有一个过时或写得不好的书，就像没有书一样糟糕。当然，大多数此类家用设备都非常相似，并且由于您很可能以前已经拥有过咖啡机的使用经验，因此您可以推断出一些东西。但是，只要这些设备在用途上相同，就可以在功能上有所不同。因为他们的开发人员必须想出独特的功能，才能在竞争对手中脱颖而出。无论如何，您可能会尝试联系支持服务，只是为了发现热线始终很忙-世界上有一半的人现在正在致电支持。对于最终用户来说，这已经看起来很糟糕。但这可能会变得更糟-可能根本没有真空吸尘器了。…

有时您只需要一只手。或雇佣军。

我与许多初创公司或小型公司合作，并且我注意到在一个几乎普遍的尴尬阶段，您需要专家来为您做某事，但您并不需要永远专职。例如，需要有人进行办公室管理：订购咖啡，管理供应商等。但是您办公室只有15个人。有人专职做这太过分了。人力资源部和公司律师也是一样。公司一直在通过聘请专家来支持数家公司的服务来解决这一问题。因此，您的公司可能有服务公司支付的全职员工的1/5份额。这对于正在进行的，泛化的并且不是超级时间敏感的事情非常有效。有时甚至有软件可以简化人们过去的工作，例如Expensify和ADP。从来没有人手工扫描过收据，并认为这是对人类努力的很好利用。这样可以无限期地兼职给您，从而解决了这个问题。但是，有些职位需要一个人熟悉您的产品，您的用户群和您的行业。对于只有一个工作室的瑜伽老师来说，并没有一个很好的应用程序可以测试您的应用程序的可用性。为此，您需要一个知道如何识别市场细分的人员和一个知道如何进行可用性研究的人员。也许您需要一位专门从事开源许可证的律师。律师对这种固定器安排很聪明。这可以通过暂时有人专职来解决问题。…

致备忘录

现在……是这样：电子邮件在本地和远程通信中都“足够好”。它也非常快，因此可以在电子邮件中进行同步对话。（这种“不太实时”的同步类型有时称为“近距离”通信。）电子邮件在所有类型的基数上也都有效：我可以仅向一个人发送电子邮件，也可以在世界范围内复制以广播我的电子邮件消息和/或开始多对多对话。短暂性的问题？嗯，人们有多种方法来组织其电子邮件以进行召回-有些设置了复杂的文件夹系统，有些从不删除任何东西而只使用搜索，甚至有些安排了电子邮件在将来某个时候返回给他们。需要它。结果如下：电子邮件的便利性（及其对几乎所有办公室工作人员的入门级访问能力）已使其成为一种占主导地位的通信形式，但这种形式却深刻而无情地侵蚀了组织的有效性。电子邮件的随意性通常会优先考虑周到的考虑和分析-因为按原样共享内容很容易。通讯的目标使按发送发送的内啡肽旅行倒退。如果有问题，他们会回答，对吗？同样，电子邮件附件允许发件人以完全不了解大多数附件的完整知识为由，声称自己已通信。而且，如果您想知道某项政策（或上一季度的数字），那么请祝您好运，并仔细研究一下电子邮件以找到它…… 电子通讯的这种污点也影响了会议的风格：会议已演变成松散的，无组织的事务，参与者和演示者都不知道他们何时进行报告，何时进行讨论或何时进行决策。像Slack这样的组织似乎将这些问题视为机遇，但是我的感觉是，他们只想用其他的“ X代表一切”来代替“用电子邮件代替一切”，但这是行不通的。专用文档格式可以帮助对齐我强烈建议组织减少对电子邮件的使用，而应以有目的的方式来组织其通信。季度报告-格式仔细…并已打印！…

如何编写用户手册

所有设备都需要指南和手册，以帮助人们有效使用产品。用户手册具有自己的特定结构，应以清晰的方式编写。开发文档是一个困难的过程，但是本文将有助于组织文档。准备工作假设您应该为设备开发用户手册。首先，请考虑将要阅读您的用户手册的目标受众。那么，如何与潜在用户进行交流呢？您可以召集一个焦点小组，但首先，准备一个有关他们的年龄，教育程度，职业以及没有什么问题的列表（如有必要），此信息将在以后为您提供帮助。然后要求他们测试设备的原型。写下他们的反馈意见，不清楚的地方，面临的困难等等。然后采访那些更了解设备的人，例如主题专家（SME），开发人员和程序员。完成面试部分后，您可以走得更远。下一步涉及阅读其他手册。注意单词的选择，样式和结构。大多数重要的和著名的公司，例如Google，Apple，Microsoft，都有自己有效的手册。但是，如果它们不相关，则不应阅读它们，而应仅阅读与您的产品和范围相似的那些手册。准备的最后一步是进行任务分析。关键在于行动计划，这对于潜在用户及其以适当方式进行产品互动至关重要。…

技术文件要素

所有技术文档的结构均类似。它们由相同的元素组成，可帮助技术作者清晰地组织文档。在这篇文章中，我准备了每个技术文档应包含的元素列表。因此，初学者可以在开发技术文档时将本文视为清单。前题是技术文档中最重要的部分。它向读者介绍了文档的标题，作者，所描述的主题，已解决的问题，使用的方法以及文档的总体目的。任何技术文件的前题必须包括以下内容：封面。它应该包括标题，作者和日期。标题应该足够清楚和详细，以便读者可以轻松掌握所涵盖内容的想法。例如，标题为“ 云层吸收太阳光”的想法无法传达文件的内容，这两个类别如何相互联系，要解决的问题。因此，该标题的改进版本可以是“ 直接观察云对多余太阳光的吸收” 。摘要是一个总结性陈述。它不应太短或太长。通常大约70-150个单词就足够了。…

52个项目第1周：一个项目跟踪应用

几周前，当我写我的第一篇博客文章，承诺每周完成一个项目时，我知道这将是一个艰巨的目标。我不认为我的第一个项目会花这么多工作。我已经进行了足够长的编程时间，以了解应用程序构建的构建基块和一般概念。当我在第1周开始我的项目时，这是一个用于跟踪我的项目构想和完成状态的应用程序，我认为这将是我几个小时即可完成的直接构建。我很快发现我错了。尽管花费了几个小时的工作时间，并且在此过程中有些头痛，但我很自豪地说我已经为项目跟踪应用程序成功构建并部署了最低限度的可行产品。随时在此处跳到实时应用程序。在应用程序中，您可以查看我使用了哪些工具的详细信息，以及对我有真正帮助的一些资源。我将Flask用于框架，将MongoDB用于数据库，将MongoEngine用于ODM，并将Heroku用于托管。在下文中，我概述了一些我称之为的“学习经历”。尽管他们引起了一些麻烦，但他们也教会了我一些重要的编程课程。了解复杂的概念：循环进口我花了至少三个小时来处理循环进口问题。我以前听说过循环导入，但是在有限的编程时间内从未遇到过此问题。我发现此资源对于理解循环导入以及如何避免循环导入非常有帮助。我的特定问题是数据库变量的实例化。在实例化数据库之前，我尝试在__init__.py文件中注册模型。解决方案是在实例化“…

受众分析在技术写作中的重要性

受众分析是所有作家都应该关注的重要问题。为什么？因为如果您的写作（无论是文章，报告，书籍还是技术文档）都不适合其预期的受众，那么这将浪费时间，精力和资源。因此，从理论上讲，您必须确保所写的内容完全适合目标受众。一个大问题但这是一个问题，一个很大的问题：大多数时候，作家并不能100％地确定他或她的听众是谁。尤其是如果您在公司工作或作为写作团队的一员，您可能会对听众的性质有一个大概的了解，但并不是一个完美的想法。所以你会怎么做？近似方法我的回答：您采用近似方法来增加写作适合您的听众的机会。这是度数的问题。您可能永远不会创造出100％适合您的听众的东西，但是通过应用经过时间考验的近似方法，您有望接近这个崇高的目标。无法访问最终用户一方面，如果您在公司环境中工作，由于非常容易理解的原因，您作为作家可能无法很好地接触最终用户和客户。公司通常不希望其作者直接与客户联系，以免他们说出会破坏销售或营销方式的内容。…