文档 – 第6页小小书 XXshu

ClickHelp 3月发布的速览：可读性得分和报告

一个新的先睹为快帖子，以及更多令人兴奋的内容！我们将在即将发布的ClickHelp版本中解决一个非常重要的主题-用户对您创建的技术文档的满意度。您肯定对用户手册的可读性有一个总体了解。但是，这个想法有没有真正的科学依据？好吧，ClickHelp将通过3月产品更新中提供的新的出色算法为您提供帮助。我们已经开发出一种精确而复杂的机制，可以使用各种指标来评估您的技术文档的可读性。分析某些指标可以让您捷径而行，可以更好地了解读者并根据自己的需求调整团队的写作风格，而另一些则可以更好地控制团队的效率。我们还添加了新的报告类型-读者人数。此功能处理独特的阅读器视图，并与现有的ClickHelp报告一起，为您描绘出用户在进入在线文档门户时的行为的真实情况。全新的可读性指标三月份的ClickHelp版本中将提供的新指标允许对文本进行非常深入和详细的分析。您可以在所见即所得编辑器的顶部找到其中一些：甚至单独的阅读时间和可读性（FRES）都可以立即使您了解所讨论主题的模样。 ClickHelp团队添加了许多您可以分析的有用指标。您可以通过单击齿轮图标并选择所需的指标来选择在页面顶部显示任何指标。新的度量标准分为以下几类：文本度量标准，常规，可读性和项目计数。您可以在一个屏幕上检查所有指标：计算可读性指标时要考虑许多因素。…

API文档的最佳做法

API现在是其游戏中的佼佼者。市场在增长，产品正在开发和改进。这意味着API文档也将成为未来几年的关注焦点。由于该领域的特殊性，API文档是非常独特的产品。因此，我们可以推断出一些主要原则，以改进该特定领域的用户指南。有了适当的文档，产品就会得到更好的采用，从而不会在客户留言中泛滥技术支持；对业务的总体影响严格是积极的。进一步，您会发现一些建议，可以帮助您创建高质量的API文档。这篇文章详细介绍了如何组织API文档的技术编写过程，如果您正在寻找有关API用户手册中应包含的内容的指南，请参阅此博客文章。让作家写作我们已经解决了这个问题。专业技术作家会创建最佳的用户手册，因为这是他们的工作，并且他们拥有正确的工具，并且对帮助创作过程有更深刻的理解。但是，API是一个难以描述的主题。它附带了您应该知道的所有术语，例如端点，方法，请求，JSON，Git等。因此，开发人员发现自己编写文档更加容易，因为技术作家似乎资格不足或不完全了解该主题。让开发人员创建API文档似乎不太麻烦，但是将来会付出很多代价。如果用户在理解如何使用产品时遇到问题，那么产品的好坏并不重要。因此，很明显，技术作者应该创建API文档，但是考虑到复杂性，我们如何安排呢？双向合作…

ClickHelp功能：上下文帮助

文档交付是一个非常重要的过程，可以以不同的格式提供。您可以发送PDF文件，发送打印的文档或在线托管文档。拥有在线文档非常有用，因为您可以立即与用户共享任何主题，并且他们可以在其Web浏览器中直接打开它。但是，您可以走得更远，并在需要澄清的任何地方直接在应用程序中插入部分文档。这样，用户可以查看其他信息，而无需切换到另一个网页甚至其他应用程序（如果我们正在谈论移动设备）。这称为上下文帮助。上下文帮助有多种形式。有时，它只是指向描述某个功能或提供说明的特定主题的链接。这是最简单的解决方案，但不是一个坏方案，但是您的用户仍然必须切换到另一个页面或应用程序。更好的解决方案是用户可以在应用程序的UI内直接获得帮助。它可以是一个小的弹出窗口，也可以是在用户需要时滑出的辅助面板。如今，Web应用程序可以轻松地将富文本弹出窗口与图像甚至视频结合在一起。可以为Context Help手动创建代码，但是可能很耗时。当您将ClickHelp用于在线文档时，有一种更简便，更快捷的方法。 ClickHelp立即为Context Help项目生成代码。由于我们的帮助创作工具基于主题，因此使该过程变得容易。…

仔细了解Document Node的写作经验

图片由rawpixel在Unsplash上拍摄专业的写作经验包括最佳的书写字体，焦点模式和格式化文本的简单方法。文档节点当前支持两种字体来编写： IBM Plex Mono iA Writer Duospace 在对焦模式下，所有内容都会消失。除了您现在表达的想法以外的所有内容。聚焦模式可帮助您深入研究流程。在全屏模式下使用聚焦模式可以消除所有干扰，包括当前句子，段落或打字机框周围的所有文字。滚动会自动停用对焦模式，直到您定居在其他位置。专注于当前句子专注于当前段落专注于打字机盒子选择键盘打字机声音可以让您只想写更多。…

写下来

我听过的最好的生产力提示之一是：•如果您必须告诉两个不同的人同一件事，请写下来。您肯定会第三次说出来，如果您写下来，可以节省一次，只说一次，就可以发送给别人。我认为可能是斯科特·汉塞尔曼（Scott Hanselman），他在2012年首届那届大会上发表了他的生产率主题演讲。我非常喜欢这个概念。写一次，任何地方阅读。我儿子出生时，我开始遵循这种做法。我记述了他的古怪举动。我没有发送家庭电子邮件，而是开了一个博客。当我的女儿加入我们时，我又开始了另一个。编写这些故事使我省却了记住它们的麻烦，而且我也不必怀疑我是否将它们发送出去了。如果我想讲述这些故事，我总是可以转发链接。我很久以来一直担任团队领导角色，多年来，我一直使用这种技术为团队生成文档。我提出了一份简短的文档清单，即使在被要求提供正式的项目文档之前，我总是会得到这些文档。您可以并且应该记录的内容，因为您当然已经多次说过：开发人员设置文档 -每个团队都会有新成员加入。有时它们是临时添加的，有时它们是永久的。…

我们需要更好的书写工具

文档节点：编写文档的更好工具多年来，我一直很难保持文档的最新状态，并且一直在思考一种更好的方法。维基系统使用Wiki是管理文档的传统方式。但是，通常我们花费太多时间来建立Wiki服务器。您必须首先在网络中找到一台计算机，选择可用端口，然后设置数据库，配置身份验证，安排备份以及进行定期升级和维护。最糟糕的是，Wiki系统提供的书写体验非常有限，而且也不鼓励对文档结构进行大量重构。例如，当您要将文档移到另一个父页面或另一个空间时，需要单击5–10次才能完成。通常，您甚至都不知道从哪里开始。当您只想重新排序几个文档页面时，也会发生同样的事情。集成开发环境如果您以Markdown或类似格式编写文档，则Intellij IDEA或VS Code等IDE可以帮助重构。但是，提供专业水平的写作经验也不是IDE的工作。另一个大问题是，如何以一种简洁的格式显示您的文档，以便其他人可以轻松地搜索，查看和共享？静态网站生成器正如您可能已经想到的那样，大量的开源项目应运而生，以帮助基于Markdown文件生成静态网站。…

适应移动设备的技术文档

相当早以前，许多产品就可以在线获取技术文档。而且，这是技术写作发展的重要一步。人们不再需要存储印刷的技术文档了。万一设备出现故障，他们不必为那本旧的I-抽屉用户手册组织搜索小组。稳定的Internet连接就足够了。现在，移动流量正在改变游戏规则。人们开始使用智能手机的数量已经超过了个人计算机，而且，所有智能手机必须提供的功能也就不足为奇了。很自然，越来越多的人正在阅读手机上的在线技术文档。尽管这个数字持续增长，但技术作家别无选择，只能适应读者的需求。统计数据怎么说统计门户网站statista.com提到，通过手机打开的全球网页所占比例从2009年的0.7％增加到2018年的52.5％。这些数字令人难以置信。在亚洲，2017年所有互联网流量的65.1％是移动设备。而且，没有理由使这种趋势停止甚至放缓。我们不会对“将整个Internet放入口袋有多么方便”有太多的了解。此现象还有其他原因。例如，移动互联网在非洲非常受欢迎（截至2017年为59.5％），因为建立固定电话连接对于某些地区而言过于昂贵。当然，另一个原因是智能手机本身以及开发人员不断投入OS UX的所有工作。…

为公开文档创建样式指南

米奇·赫德伯格（Mitch Hedberg）说：“当您在好莱坞而且是喜剧演员时，他们希望您除了喜剧之外还能做其他一切。他们说，好的，你是一个喜剧演员。你会演戏吗你能写吗？给我们写一个脚本！ …这不公平。好像我是个厨师，我努力工作成为一个好厨师，他们说，好吧，你是个厨师……你能种田吗？” 如果您是负责编写技术文档的开发人员，那么您可能会有点像Mitch写笑话时的样子。在今天的帖子中，我们将讨论为何拥有优质的产品文档很重要，以及开发人员在创建产品时有时会面临的独特挑战。为了帮助您入门，我们将介绍写得很好的文档的一些核心原则，包括如何创建技术风格指南。太好了-我们将立即让您耕种。优质用户文档的重要性在一个完美的世界中，您只需要开发非常易于使用的应用程序和工具，甚至不需要用户文档。不幸的是，几乎从来没有这样。即使您认为您可能已经在银河系中发布了最简单，最直观的产品（某人某处），也不会得到它。并且不可避免地会有人成为您的用户之一。…

我在2018年玩过的游戏清单

“最好的”列表很有趣，但是我想我会发布一份我记录的2018年所有游戏的非分层列表。我当然忘记了一些，可能会有一些误分类，但这基本上是准确的。它们中的绝大多数是小型/短游戏，而且我敢肯定它们都不超过20小时。另外，我认为一次完整播放是“完整的”。已完成（172） 1 0000年 2N1 50 e 6180月亮一个小巴士站艾伦·潘（Alan Pain）-醒来！艾伦·威克的美国梦Night 沉默节录阿卡迪亚波斯菊茄子…

从学术界到技术写作

我已经写了大约十年的文章。我喜欢写作，我认为这几乎是我的第二天性。每当我想分享，创建或做某事时，我都会从写作开始。现在，我开始以谋生为目的，这很棒。但是每当我不得不告诉某人以什么为生时，我都会收到奇怪的表情。技术作家是“ 专业的信息交流者，其任务是在两个或更多方之间传输信息（知识） ”。在初创公司和软件公司中，这意味着“文档的所有者”。技术作家是负责向开发人员，管理员和最终用户解释难题的人。技术作家通过编写出色的文档来做到这一点：指南，操作方法，API文档，参考以及任何可以使某人的生活变得轻松的文档。技术作家旨在通过创建每个人都可以遵循的说明和文档来为产品增值。因为如果您的产品具有一项功能，但是没人知道如何使用它，那么您的产品就具有一项没人会使用的功能。在对技术写作这一概念进行了快速介绍之后，我想分享一下我如何踏上这一职业道路。科技写作之旅在成为技术作家之前，我曾是瓜达拉哈拉大学的兼职教授和研究员。我正在完成电子和计算机科学的研究生学习。但是当我开始学习时，英特尔与我联系。…