技术写作 – 第7页小小书 XXshu

我的7条技术写作诫命

资料来源：pexel.com 是否曾经想写技术博客？我也是。我的问题是，我从未真正知道如何去做。就我而言，科技博客作者就像JK Rowling。他们通过写魔术来制造魔术。我承认这有点吓人，但我下定了决心。通过阅读几篇技术文章（由媒体提供），我发现了其中大部分重复出现的一些规则。我将它们称为技术写作的7条诫命，稍后将对其进行分解，但首先要了解 “如果其他人对此主题写过任何东西，那都没有关系。就像您的编码样式对您来说是唯一的一样，您的文学样式也是其中一种。没有人能比您卖得更好。如此自由而公开地说话。” 资料来源：pexel.com 规则1：不要说话，除非您有话要说昆西·拉森（Quincy Larson）将此称为“物质”。…

技术文件标题

技术写作的主要目的是清晰地解释困难的事情。为了使大文本易于理解技术写作人员通常将信息分成小块，并在标题上加上标签。标题应显而易见，并传达本节的含义。那么如何正确组织您的文档呢？继续阅读本文！首先，让我们谈谈技术写作文档本身。最好使用短句并保持您的语言简单。这将使您的手册更加易懂。为此，请简要介绍信息。因此，如果一个人只想更换火花塞，则无需描述发动机的历史。人们通常使用手册来解决问题。这意味着您应该向读者提供技术文档。所以你应该怎么做： · 使用适当的样式。技术文档应包含重点信息。这就是为什么使用笑话，典故，隐喻等来接受是不可接受的。…

选择技术写作工具

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

2年技术写作的5个思考

昨天是我进修技术写作的两周年纪念。我想说这是一个漫长的旅程，但在大多数情况下，这对于大学毕业和入职的人们来说是正常的职业。但是，没有艰苦的工作，艰难的决定，成功的项目，与同事的分歧以及RL Stine式的一些曲折就不会出现正常现象。当我回顾过去的岁月时，首先想到的是这个周年纪念日几乎就像一个生日。快到生日了，因为又过去了一年，而我也越来越接近白发了。我喜欢认为这将使我有一天变得更加杰出。希望这不会是我与这个职业的唯一区别。因为我想取得更多成就。我认为，认真研究自己的职业并反思自己去过的地方，做过的事情以及想要完成的事情至关重要。通过在两个不同行业中从事两项工作，我发现有些事情交叉了，而另一些则变成了该领域的对立面。我已经缩小了过去几年中我认为最重要的五个想法。学习词汇词汇是人，语言或知识分支的词汇。我注意到词典根据行业，产品，有时甚至是一个人的职称而有所不同。无论哪种方式，加快行业使用的速度都是至关重要的。每当我进入新工作/行业时，最大的艰巨任务就是为正确的过程学习正确的术语。从软件开始，我不知道什么是API，做什么SQL，如何通过工作流运行订单。…

斯里兰卡及其社区的技术作家

我们在2018年4月26日创造了历史！我们在这个美丽的岛屿斯里兰卡举行了第一次技术作家（TW）聚会。与志趣相投的人见面，交流和用餐，分享我们的经验真是太棒了。当天有两个讲座。它们涵盖了技术写作中内容和质量的重要性，以及《通用数据保护条例》（GDPR）如何影响技术文档。后来，我们分成了小组，讨论了我们作为技术作家所面临的挑战，当前的趋势和技术，技术写作的职业道路，培训和认证的重要性等。很高兴听到与会人员的新想法。并了解他们如何管理组织中的内容。总而言之，我们很高兴在斯里兰卡创建了TW社区（简称TWSL社区）。在WSO2，我们有16位技术撰稿人，我们喜欢互相交流并分享我们的经验。昨天，我们意识到有超过16个人热衷于技术写作，这真是一种令人敬畏的感觉:)。举行第一次聚会或组建这个社区并不是一朝一夕的事。 WSO2的技术作家孜孜不倦地工作，以实现这个梦想。许多人以各种方式帮助了我们。看到2018年4月26日事情如何融合真是太神奇了。 WSO2的技术编写者有一个计划，但是每个人都确保计划中的每个项目都已执行完毕。我以前在团队中工作过，但是没有看到这种热情（您需要记住，所有这些额外的任务都必须在平衡工作任务的同时完成。.这并不容易）。管理社交媒体网站的人员在建立社区和传播信息方面做得非常出色，而管理见面会管理任务的人则确保在见面会当天一切都按计划进行。现在，我们计划与TWSL大家庭一起成长，一起学习，了解新趋势等。斯里兰卡所有技术作家的目的都是将技术写作提高到一个新的水平。…

日间工作

照片来源你们中的许多人都在Medium帖子中写了关于您的日间工作的信息，说实话，除了沉迷地检查您的Medium stats之外，了解自己的工作也很有趣。无论您是IT专业人员，自由职业者，还是冠军牡蛎剔除者-无论是什么，它都可能会影响您的写作。试着猜测我做什么工作。继续，尽力而为。那是什么？你让我钉为卡尼吗？不错的尝试，但我只会讲流利的言语交流，实际上我并不是这样谋生的。虽然我确实知道如何制作踢屁股的蛋糕。我是一名技术作家，显然会带您想到“技术作家？她可能精通一些有趣的主题，例如DITA和XML编辑器以及Inverted Pyramid。我喜欢谈论这些主题，尤其是与毫无戒心的人在聚会上向我自我介绍。我也是一个三重威胁，因为一旦我用完了技术写作主题，我就会顺利过渡到《指环王》琐事，然后问你最近是否有任何有趣的梦，我将在我的梦中进行解释。头，比您可能想让我知道的更多有关您的知识。善于社交和娱乐！这是成为技术作家的其他一些有益的副作用（除了使我成为超级棒的会话主义者）。注意：在向所有人发送私人笔记询问您如何也可以参与这项技术写作之前，请理解，它并不适合所有人。…

“我应在技术或商业副本中使用“我们”还是“我们的”？”

不，你不应该。期。不使用文档（尤其是商业副本）中的“我们”和“我们的”不仅更专业，而且出于一个简单的原因，不要这样做是明智的– 客户对美国不感兴趣。他们对他们感兴趣。一个恰当的例子：在任何网站上阅读量最少的页面都是“关于我们”页面。没人在乎。这通常是浪费空间。接受这个普遍的公理事实，然后从那里开始。作家（尤其是技术或复制作家）在那里解决其他人（不是美国）遇到的问题。一旦您接受读者对您不是作家的兴趣，您就可以自由编写每次都能达到目标的有效副本。去问问任何值得他或她吃盐的撰稿人，他们会告诉您英语中有两个MAGIC单词：1）…

如何衡量文件的有效性

by ClickHelp —专业的帮助创作工具技术写作和交流涉及将复杂的信息清晰，准确地传达给特定的受众。这里的关键词是交流，是双向互动的术语。但是在技术性写作的情况下，收信人这一面笼罩在神秘之中。技术作家通常对最终用户，他们的能力水平和需求有一个非常模糊的想法，因为他们缺乏听众的知识和反馈。但是，对目标受众的知识有清晰的了解对于调整特定受众的写作需求并以适当的方式传达信息至关重要。在本文中，我们将重点介绍收集指标的方法，这些指标可进一步用于改善文档质量和用户满意度。 Web分析是一种功能强大的工具，可用来衡量用户体验。您可以使用Google Analytics（分析），Adobe Analytics或其他一些Web分析服务来收集有关目标受众的最基本但仍有用的信息。它将为您提供以下指标：在特定页面上花费的时间。每次访问的浏览页面数。页面访问次数，等等。例如，ClickHelp技术写作工具具有内置的统计信息功能，该功能允许监视特定主题或整个项目的查看统计信息。…

停止将Markdown用于文档

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

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

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