文档 – 第4页小小书 XXshu

选择技术写作工具

by ClickHelp —专业的帮助创作工具技术作家使用记事本或MS Word创建用户手册的时代已经过去。现在，我们有一个庞大而充满活力的技术写作工具市场。但是，出现的解决方案越多，找到最合适的解决方案就越困难。或者，甚至找出要考虑的正确参数。由于我们在这一领域拥有丰富的经验，因此决定创建此文章以对您有所帮助。因此，这里是选择技术写作工具时要注意的关键参数。与团队合作相关的功能也很重要，即使我们谈论的是很小的文档团队。如果存在协作，则必须建立一些工作流程。否则，将是一团糟。如果团队很小，我们不会将其称为灾难，但这仍然是一种令人不安且耗时的情况。因此，一个好的技术写作工具应该具有团队协作的功能，例如：用户角色，电子邮件通知，文档状态和版本历史记录。而且，以防万一您难以在团队中实现更好的协作，您还可以查看我们的博客文章“如何优化文档团队工作流程” 如果您已经搜索了帮助创作工具的市场，那么您会发现以下比率：大多数应用程序都是为Windows平台开发的。就Linux和MacOS而言，您没有太多选择。…

停止将Markdown用于文档

嗨，大家好！今天，我想解释一下为什么Markdown是一个写得不好的工具，您应该避免在文档中使用它。介绍 Markdown是Internet上最著名的轻量级标记语言。它用于自述文件，介绍指南，Wiki页面，博客文章，评论。它的流行是基于简单性和较低的编写阈值。您可以在60秒钟内学习所有语法，几乎立即就可以使用自己喜欢的IDE开始编写第一个文档。在撰写快速说明以描述产品功能和基本用法命令时，这特别好。 GitHub和GitLab甚至允许开发人员使用README.md文件自动启动新存储库，尽管两个项目都支持多种语言，包括Asciidoc和reStructuredText。让我猜你的问题-这样一个受欢迎的工具怎么会这么糟糕？它真的有很多缺点吗？实际上，它们比您想象的要多。为什么Markdown失败？我想概述一下最烦人和令人沮丧的限制，这些限制可能会使您用Markdown编写技术文档时的经历变成一场噩梦。缺乏规范。自2004年推出以来，Markdown一直没有技术规范，只有John Gruber在其博客文章中定义的规范为止。…

使用Google文件的指南建议的编辑更改模式

Google文档允许您在与他人协作处理文档时建议对文档进行编辑更改，而无需在文档所有者接受或拒绝之前替换原始文本。现在，审阅者建议直接在文档中进行编辑，而不仅仅是在注释框中。如果您在查看文档时在Google文档窗口的右上方查找，则会在以下三个状态之一中看到当前状态：编辑：允许您直接键入，添加和编辑文档。然后，您可以与任何同行共享您的工作。建议：允许编辑者对文档的更改提出建议，而无需删除作者的原始作品。基本上跟踪您的更改编辑。查看：阅读或打印文档视图，以确保所有错误均已更改和编辑。建议和评论被隐藏，您无法在查看模式下编辑文档。分配评论权限建议对文档进行更改评论建议什么时候需要使用建议的编辑或注释？一项或多项接受或拒绝建议接受或拒绝所有建议…

“您能提供一些技术作家可以写的技术文档的例子吗？”

拉起椅子并使自己舒适。这是技术作家可以创建的所有疯狂的各种文档的选定列表：各种产品，服务，软件，硬件，网络，系统和小工具的用户指南和手册。各种产品，服务，软件，硬件，网络，系统和小工具的配置指南和手册。适用于各种产品，服务，软件，硬件，网络，系统和小工具的系统管理指南和手册。各种产品，服务，软件，硬件，网络，系统和小工具的安装指南和手册。适用于各种产品，服务，软件，硬件，网络，系统和小工具的快速入门指南和手册。有关各种产品，服务，软件，硬件，网络，系统和小工具的参考图表和数据表。有关各种产品，服务，软件，硬件，网络，系统和小工具的发行说明。产品，服务，尤其是软件，硬件，网络，系统和各种小工具的系统体系结构和规范指南。…

如何编写技术文档

如果您不是技术作家，但需要创建文档，则此快速指南将帮助您采取正确的方法。仅需6个步骤，即可帮助您计划和组织内容，并避免常见错误。请注意，这些技巧用于记录产品和服务。如果要求您编写API文档，则将需要其他方法（尽管某些原理是相同的）。 1.考虑为谁写作第一个技巧是弄清楚您正在为谁写作。如果您不能直接问客户，请与与客户打交道的任何人交谈。向他们询问客户有什么问题，以及他们了解和不了解什么样的术语。您还可以使用网络上的关键字研究工具来查看人们正在搜索的术语。 2.列出任务不要写产品功能的描述。这对读者不会有太大帮助。相反，请考虑客户可能需要执行的所有任务。您可以通过创建“如何做”任务的列表来解决这个问题。这将是一个不错的开始，但是在编写内容时，请勿在每个主题的开头放置“操作方法”，因为这会使内容难以使用。 3.使用信息类型如果您不是技术作者，则不太可能了解内容重用功能和信息类型。没关系。…

当今的数字办公室[信息图]

过去，在办公室工作是一种非常类似的经商方式。即使使用诸如计算机，打印机，传真机和复印机之类的技术来简化您的生活，仍然有大量手动执行的低价值任务，并且占用了大量时间。老实说，谁真正有时间了？幸运的是，随着世界变得越来越高科技，办公场所正在以相应的速度升级和适应。鉴于以前您受到许多物理过程的束缚，现在您可以以您从未想过的方式简化生产力。今天，我们将探讨当今数字办公室的现状。我们正在谈论技术如何与传统工作场所融合，以使每个人（从接待员到首席执行官）都更加投入并提高生产力。在过去，管理所有旧文件意味着您必须打印大量数据并将其存储在文件柜中。所有这些过程都使您的工作浪费了宝贵的时间，仅存储本身就效率低下且成本高昂。更不用说，经过所有的组织和分类，您甚至可以在需要时找到该文件吗？好吧，幸运的是，匆匆忙忙地浏览文件柜数小时的日子已经过去了！光学字符识别（OCR）和基于云的存储等技术使文件管理变得轻而易举。您不仅可以扫描物理文档并从任何门户网站（例如，计算机或平板电脑）访问它们，还可以在对其进行扫描后从流通中删除它们。简而言之，与文件柜告别，打印和浪费时间查找归档的文件数小时！即使您的办公室是所有员工的中央枢纽，但这并不意味着他们必须整天坐在办公桌前。随着互联网渗透到我们的日常生活中，仅需一台支持wifi的设备，您的员工无论身在何处都可以完成几乎所有工作。工作场所的移动性对于数字办公室的生产力至关重要。借助wifi和便携式设备，员工可以利用拥有现代化公司办公室的惊人好处。…

文档：最糟糕的写作，拥有最好的写作

在我们脑海中的某个地方，从事软件项目的每个人都知道文档是一件非常好的事情。尽管有这种意识，但文档的优先级通常低于其应有的优先级。许多可以理解的动机导致文档的优先级较低。为了正确确定文档的优先级，我们需要检查组织面临的Document-Discouragers©。 Documentation-Discourager 1：没人要阅读它一定比例的文档可能永远不会被阅读，但是文档的好处胜过偶尔未读页面的弊端。也就是说，除非团队养成习惯使用文档，否则文档无用。每当您被问到问题时，这都是一个鼓励阅读文档的习惯的机会。如果有可能，请不要回答。相反，请提供指向文档的链接。如果不存在任何文档，其他人可能会再次问到这个问题，请先创建文档，然后使用链接进行答复。除了节省将来的击键操作之外，这还创建了一个集中的信息源。它消除了发生某些更改时获取过时信息的风险，并且获取此信息不再取决于某人答复电子邮件。 Documentation-Discourager 2：我写的东西实际上有用吗？文档化的最大好处之一就是可以从根本上防止问题的发生。经历一个问题要比没有发生要突出得多，因此很容易忘记文档的实用性。…

如何通过简单的操作创建很棒的数据表

数据表是重要的产品文档之一，如白皮书。数据表是您产品的ID，它是公司与具有截然不同需求的客户之间（即买卖双方之间）的重要沟通链接。对于潜在客户，数据表代表了公司本身。与客户的连接点数据或产品表是在销售点到达客户的最后文档。因此，它们必须经过精心设计，并具有清晰的产品说明和购买动机。让客户访问产品信息可以减少购买障碍，并为您提供一个展示产品的优美平台。该数据表模板是通过TDSmaker设计的，可在免费模板库中找到。所有公司都为技术表设计自己的公司模板。这些工作表是使用带有徽标，公司名称，联系信息，产品名称代码，内容设计等的特殊布局进行定制的。尽管有些公司确实获得了设计机构的模板设计支持，但其他公司的数据表模板却是由其设计的。自己的员工。旧方法增加了出错的可能性。从旧文档中复制和粘贴内容会增加视觉和内容错误。最常见的错误是，例如，来自其他文档的无效表达式，字体差异和拼写错误，这些都会对专业外观造成不利影响。为了最大程度地减少人为的错误，必须检查和更正文档，但这会占用您宝贵的时间。为了节省时间并保持最新状态，请将信息传输到模板。在编辑有关技术数据，产品的特定使用区域和其他基本用户信息的信息时，可能需要一个以上部门的协作（取决于公司的组织结构）。类似产品的数据表和实验结果也用于内容创建。许多公司将这些数据放到通常使用Microsoft…

技术交流员：为什么我们很少在野外找到它们

技术交流者是一个难以捉摸的物种。他们依靠复杂且无法使用的技术为生，并捕食毫无意义的文字，但没有人真正了解这些生物的行为。您可能知道他们是技术作家，信息开发人员，知识工程师，莎士比亚，也是我个人最喜欢的：“写作的那个人”。训练有素的眼睛可能很难区分他们，但是如果您想找一个“那个写作的人”，您将找不到技术交流员。如果您正在寻找技术作家，您将找到一个“写作的人”。仅仅因为它有条纹，并不意味着它是斑马。当然，技术交流者需要出色的写作技巧，但这远不能定义角色。业界中所有公认的术语都太狭窄，无法定义真正使技术传播者成为现实的东西。写作是容易的部分！除了样式，一致性和语言能力外，任何人都可以编写解释某些内容的过程。为了组建Feedzai的Tech Comm团队，我们面临着写作方面的挑战，许多具有写作或语言学经验的应聘者会在没有格式或标点符号的情况下传递文字，这种文字通常太复杂且难以阅读。看看我在那里做什么？剧透警报：不聘用这些候选人。 10个关键特征有10个关键特征可以帮助我们区分技术交流者和撰写者。技术交流员：了解核心信息并考虑读者需要学习的内容，并专注于解释真正相关的内容。…

我总是忘记喝水，所以我建立了一个Twitter机器人来提醒我

这些天来，我一直很难保持水分充足……尤其是在家里。几个小时，我沉迷于一本书，忘了喝水。这导致我的皮肤和嘴唇变得更加干燥。最近，我跟随许多机器人来帮助我进行世界建设。将这两个想法结合在一起，我想为什么不建造一个机器人来提醒我喝水呢？我一直在dev.to的阅读列表中找到这则特殊的帖子，就在本周，我决定终于阅读它。在研究过程中，我也偶然发现了该帖子，并最终关注了它而不是前者。现在，这就是我想要发生的事情（最初）。我只是想让机器人提醒我每3小时要喝水。因此，这是我如何实现这一目标的思考过程。在本地构建原型。将其设为tweet而不是转推（请参阅第一个教程）每3小时发布一次推文让它喷出̶r̶a̶n̶d̶o̶m̶̶n̶o̶n̶s̶e̶n̶s̶e̶鼓励的话让我喝水创建句子生成器的算法部署方式我去了Twit的文档，并寻找了如何发推而不是转推。自述文件有点混乱，但可以理解，所以很好。…