文档 – 第7页小小书 XXshu

应该认为技术写作很无聊

©Ugur Akinci 是的，应该进行技术写作！ “无聊”意味着“零方差” 出现零方差时我们很无聊。当事情没有改变。好的技术写作每次对系统如何工作或如何完成任务的描述都必须零偏差。例如，如果我们在第2页上将过程称为“子例程”，则必须在第34页上将同一对象称为“子例程”而不是“程序线程”，否则用户可能/将感到困惑并最终做错了事情。想象一个飞行员…… 想象一下，您的飞机是由一位飞行员驾驶的，他接受了非常“激动人心的”和“热闹的”培训手册的培训，该手册将提高飞机速度描述为一页上“踩油门”，另一页上“放开飞机”，另一个“将加油杆拉到位置X4”。你相信那位飞行员吗？我不会技术写作的目的不是娱乐。目的是教您如何以相同的方式每次都始终如一地解决问题，而不会出现任何错误。为此，它必须是“坚硬的岩石”，这意味着它必须具有“ 零方差”…

记录组件的神话

系列记录组件中的7中排名第7：总览 | 简介| 例子设计代码创作| 神话我反复揭穿有关制作组件文档的神话。在我设置每个系统时，一遍又一遍地遇到它们是一个挑战。但是，我将利用这些机会使自己逐渐形成自己的信念，以实现更好的程序。这是其中的八个。误区1。优质的文档是即时，廉价和容易的您认为草拟，审查，迭代，编辑抛光，生成图像，代码示例和演示，然后发布与Google Material或Morningstar Card页面一样精细的页面仅需要花费几个小时？…

在技术写作团队中使用词汇表

by ClickHelp —专业的帮助创作工具技术写作是一个全球性的概念。技术文档是在世界上许多不同领域编写或本地化的。试想一下有多少技术术语。即使您长期从事技术写作，在一个行业中工作，也并不意味着您会完全了解该行业的所有术语。而且也不应该！一个简单的例子-软件文档。每个新功能都带来了与之相关的新词。或者，有些术语非常深入和复杂，因此在用户手册中很少出现。而且，另一件事-您不是机器人，因此您无法了解/记住所有内容。但是，众所周知，所有术语应正确使用并在用户手册中正确解释。这就是为什么词汇表对于技术作家来说是一个好主意。让我们从头开始。什么术语？术语是在特定上下文中具有特定含义的词或表达。此外，在这种情况下，这些词的含义应该非常精确。…

ClickHelp 3月发布的先睹为快：增强的审核流程

今天，我们真的很高兴为您提供ClickHelp March版本的独家介绍。我们已经准备了许多产品增强功能和功能更新，并渴望与我们的客户分享！接下来的几周将有更多偷偷摸摸的帖子发布。复习是技术写作的关键部分。而且，考虑到这一点，ClickHelp团队在3月产品更新中尽了最大的努力使此功能更好。审阅者为您的帮助主题带来了新的视角，并展示了解决和改进它们的方法。当技术撰稿人完成一个帮助主题时，您可能不会称其为完整的fixer-upper，但对于审阅者而言，它仍在进行中。进一步阅读以了解我们的在线文档工具变得多么容易和直观。待办事项清单当您在目录中的主题标题旁看到带有数字的绿色方块时，这意味着该主题存在一些待办事项。也有一封电子邮件通知，但是，我们认为直接将此类指示添加到TOC使得跟踪进度非常容易。绿色正方形中的数字显示该主题还剩下多少未完成的项目：如果您打开主题并单击页面顶部的“待办事项”，您将在屏幕左侧看到“待办事项列表”面板。此类列表通常包括您需要在相关主题中添加或更改的一些内容：如您在上面的屏幕快照中看到的，两个项目被标记为已完成，因此，处理此帮助主题的技术作家仅需修复最后一件，将项目标记为已完成，文档即可准备进行另一次审阅迭代。为方便起见，如果子主题中有未解决的待办事项，则父主题中的TOC旁边会出现一个绿色圆圈：同样，ToDo列表通常也用于制定新主题的计划，因此不会丢失任何细节。…

有助于技术写作的软技能

软技能通常在技术写作中被忽略。人们只有在情况严重时才开始认真对待他们。就像，当您意识到自己的时间管理能力很差，以至于影响了您的职业发展。积极主动地运用软技能真是太棒了，因为它们可以使您的职业生涯变得更加轻松，防止倦怠并提高绩效。在本文中，我们将讨论技术作家的软技能以及如何从今天开始开发它们。通讯技术作家需要进行的交流远远超过了人们的想象。 Doc团队可以与公司中的任何部门进行与工作相关的对话，但是，当然，主要的沟通渠道可以导致主题专家或SME的简称。交流作为一个概念包含许多方面。让我们看一下其中的一些：提出正确问题的能力。一项非常重要的技能。提出正确的问题后，答案将更加明确，并且您将花费更少的时间对所获得的所有信息进行系统化和分类。忍耐。每个人都是不同的，这给清除自己的沟通造成了障碍。最重要的是，我们只是人类，所以情绪波动和个人事务也会干扰。即使是我们最好的人，也不一定总是能够阻止我们的内心状态影响我们的工作。因此，您应该对他人和您自己保持耐心。…

您如何组织笔记和链接？ – 一项研究

强迫记笔记/链接保护程序的自白。这篇文章是关于组织信息的。更具体地说，它涉及保存注释，链接，书签的方法，以及为什么这样做很重要。这篇文章是关于“笔记系统”的。这是一个书呆子的帖子。我的意思是，您必须在某种程度上喜欢书呆子，热爱做笔记，在大部分的清醒时间里都在记笔记并记下自己的世界。大约二十年前，尼尔·邮递员（Neil Postman）在他的《通知自己死亡》一书中宣布，我们正在“沉迷于信息”。新闻周期中发生了太多事情，每天都有如此多的内容在线发布，我认为没有人会反对这个想法。引用如下：但是，从解放之流开始的东西已经变成了一片混乱。 ……如今，事情已经达到如此严重的程度，以至于对于普通人来说，信息不再与解决问题有任何关系。 …信息与行动之间的纽带已被切断。 ……它是无区别地出现的，特别是针对任何人，都没有有用性；我们到处都是信息，淹没在信息中，无法控制它，也不知道该怎么办。…

偷看一下ClickHelp更新

好吧，我再也忍不住了。我只是绝对要告诉你。此外，我们已经在公司博客上正式发布了一些内容，因此… 在过去的一年中，我们一直在努力进行新的更新。实际上，我们没有特定的日期或类似的日期，我们只是在收集用户的反馈，仔细查看最新趋势以及人们的普遍需求并开展工作。努力使我们的工具更好，更快，更容易被更多的受众使用。在过去的一年中，我们做了很多工作，完善了ClickHelp。尽管我现在还不能发布该版本的概述（尚未发布，嗯），但我已经被授予自由给您一点偷看的机会😅 说实话，我什至不知道从哪里开始。当我联系我们的程序员并要求提供一些可以帮助我编写此偷看内容的内容时，他们向我发送了一个变更日志文件，其中包含数百行新功能/改进/修补程序/等。 * 深呼吸 *好吧…事不宜迟，让我们快速看一下ClickHelp的March Release的最大功能。导航在即将发布的版本中，我们显着改善了技术撰稿人/审阅者和读者的导航。 mini-ToC的一个例子索引关键字（Taxonomies）就像标签，您可以将其分配给主题。…

文档化的文档化宣言：如何在敏捷团队中维护文档

如果一家科技公司没有每隔15分钟就谈论他们如何成为“快节奏，敏捷的工作环境”，那么他们实际上是一家科技公司吗？撇开所有笑话，我真的很欣赏敏捷的哲学。以结果为导向的项目，迭代式开发，自我授权，协作和信任都构成了一个出色的工作环境。但是，我想讨论敏捷宣言的四个价值之一：工作软件胜过全面文档正在编写1.4.03版补丁说明的初稿在最初启发“ 宣言 ”的背景下，这种说法很有道理。呆滞在滑雪场上重塑发展实践的17个人来自疲软的公司环境。除了支持其他无意义的流程之外，对那些没有贡献任何现实价值的流程进行的巨大投资令人心碎。文档仅凭现有的优点就可以存在，并且随着给定业务中技术的变化，它很快失去了价值。对于想要以不同方式拥抱工作的人们，采取这种立场既大胆又振奋。但是，我认为行业很容易误解敏捷原则，因为它是一种工作哲学，而不是具体过程。 Scrum方法论可能是最流行的敏捷原则框架，但是即使该框架也被明确设计为开放式的。敏捷的好处同时为滥用提供了机会。对于半完成的项目，业务可以证明对功能需求进行枢轴调整是合理的，因为它们包含对变更的响应。…

ClickHelp Aurora Polaris更新

我们做到了。在过去的一年中，我们不懈地努力为您带来最好的在线文档软件。我们将工具颠倒了，添加并重写了无数行代码，显着改善了UI和整体用户体验，实现了许多很酷的功能以及许多其他功能，因此您可以更高效，更轻松地创建文档简单的方法。更改日志如此之大，您甚至可以将其称为ClickHelp 2.0，但我们决定变得更加微妙，并推出名为Aurora Polaris的第一个主题版本。但这并不意味着我们要从地下室的散热器中解脱程序员-我们将确保继续磨练我们的工具并进一步改进它，直到达到无法实现的理想水平。准备好了，因为这会很长。所以，我们可以吗…？审查与合作在此更新期间，我们集中精力于审核过程。毕竟，审查技术作家编写的文档是其生命周期中必不可少且非常重要的一步。我们希望为您提供强大的协作工具，同时又简单又有效。看看这个坏男孩：您看到的数字和点表示您的主题中有一些需要您处理的内容。正方形数字表示确切的主题包含一些未解决的项目，而小圆点表示子主题之一包含它们。待办事项清单因此，绿色的东西是待办事项。…

你好LaTex

作为Microsoft的忠实用户，项目迁移到Latex的要求使我感到不寒而栗。在开始潜水之前，我就吓坏了。 “我也必须对文档过程进行编码吗？”我烦躁地想。没有其他选择，我首先下载了Miktex。最初的几次尝试进一步激怒了我，因为下载速度非常慢，每隔一分钟就会失败。一个下载管理器终于解决了这个问题。安装顺利进行，让我松了一口气。看完一些视频教程后，我从文档的第一块开始。编写纯标题的代码再次激起了Microsoft Word的分离焦虑。 “我们如何将事情视为理所当然”！我第一次成功运行文档时就跳了字。我忘了意识到，从现在开始，我将不得不“运行”文档而不是仅仅打开它。随着我学到更多，我开始喜欢它。我的格式设置一直很糟糕。我无法区分对齐文本和不对齐文本。谢谢上帝，一直以来为我所做的朋友。令人高兴的是，我现在可以不用依赖其他人而摆脱这项艰巨的任务。…