软技能

指标读者本课程的指标读者为已实现技术写作 第一课[1]，然而依然渴望进行更多写作培训的人员。如果你没有承受过任何技术写作的培训，最好先看一下第一课能容。 学习指标这节课侧重于技术写作中的几个两头主题，学习完本课程之后，将播种如下的常识： •从几种不同的策略中抉择一种编写第一稿的策略，以及第二稿、第三稿的其余策略。•应用多种技术来检测写作中的谬误。•学会组织大型的文档。•介绍文档的范畴和所有先决条件。•写下清晰的图形题目。•在技术插图中抉择适当的信息密度。•将读者的注意力集中在插图上。•通过图片建设上下文。•无效的批改技术插图。•创立有用、精确、简洁，清晰，可重用和正文良好的代码，用来演示一系列的复杂性。•标示不同的文档类型。•形容所有的内容。•谅解初学者，并为他们编写教程。 成为一名优良的工程师或者优良的技术作家都须要破费多年的专一实际，这门课程能进步你的写作水平，但不会立刻使你成为一个杰出的作家。 自我编辑参考《Google开发分档格调指南[2]》 换位思考： •尝试从读者的角度浏览文档，确保文档目标是明确的；并思考好不同的角色所领有的常识储备。•而后从作者的角度浏览文档，确保你做的假如有用，还能够提供资源的链接。•最初请留神，过分依赖角色，会导致文档过于狭窄，而无奈对大多数读者有用。 大声读出来： •本人大声的朗诵或者应用屏幕阅读器朗诵，来听取难堪的措辞，简短的句子或其余不天然的内容。 编写每一搞的策略： •编写完每一个版本之后，先放边上一个小时，而后再回来浏览一遍，总会发现有能够改良的中央，举荐做三遍。 查看写作中的谬误： •邀请某人查看你的文档，并给你具体的，建设性意见。•浏览的人不肯定是同行，然而最好相熟你遵循的文档格调。 写一个大型文档应用以下策略能够帮忙你们撰写大型文档： •抉择编写单个大型文档或一组简短文档。•把简短文档整顿为一个大型文档。•给大型文档增加导航。•逐渐裸露信息。 什么时候写大文档： •当你的浏览对象是刚入门的读者时，写操作指南、入门概述和概念性指南通常能以短文的模式提供更好的作用。•当曾经对工具和主题有肯定教训的读者，写深刻教程，最佳实际指南和命令行参考页能够作为更长的文档应用。•好的教程能能够依附叙述来疏导读者实现较长文档中的一系列相干工作。 写较长文档的办法： •创立纲要和起草宣言。•实现初稿之后，能够更具概述和简介对其进行复审。 编写纲要的实用技巧： •在要求读者执行工作前，先解释为什么要执行此工作。•将纲要的每个步骤限度为形容概念或实现特定工作。•结构轮廓，以便文档在与读者最相干时引入信息。•在起草前，先与贡献者共享纲要内容。 能够提供一个根本信息来介绍文档： •阐明文档涵盖的内容。•心愿读者具备哪些常识储备。•阐明文档没有涵盖那些内容。 为文档增加目录，可确保读者能疾速的找到所须要的内容，清晰的目录包含： •简介和摘要•主题清晰•有助于用户了解的题目和子标题•提醒用户在目录中的地位•能够通过目录能跳转到相干地位•有下一步学习的链接 在每个题目下都进行简短的介绍，防止在题目前面马上放入下一级题目。 图片在插入图之前写题目会很有帮忙，而后，插入能阐明题目的图片 图片中好的题目应该具备上面的特色： •他们很简短，通常只是几句话。•阐明了重点。•能吸引读者的注意力。 思考以下三个图形，每个图形应用雷同的题目。 题目A。单链接列表蕴含内容和指向下一个节点的指针。 题目B。单链接列表蕴含内容和指向下一个节点的指针。 题目C。单链接列表蕴含内容和指向下一个节点的指针。 上述三个题目中题目C是最具启发性的，题目清晰的形容了图片的性能。 如下图片中的信息量不要过大。 如上图的复杂性就会让很多读者望而生畏，就像防止过长的句子一样，请尽量避免较简单的图片。 将简单的图片变为连贯且有用的窍门是将简单的零碎组织成子系统。 图4.分为三个子系统的简单零碎。 显示大图之后再别离提供每个子系统的图片。 图5.简单零碎的一个子系统的扩大细节。 画图工具 •Google绘图[3]•diagrams.net[4]•lucidchart[5] 创立示例代码代码依然是技术人最喜爱读的，好的代码通常是最好的文档。 好的代码样本是正确、简洁，你的读者能够疾速了解它们，并能以最小的代价重复使用它们。 正确示例代码应该满足上面条件： •代码构建没有谬误。•能按要求进行执行。•要做好生产应用的筹备，比方，代码不能有安全漏洞。•遵循语言的约定。 简洁示例代码应该简短，仅包含根本组件，不相干的代码可能会使你的读者扩散注意力。然而，也不要用谬误的做法来缩短你的代码，在正确和简短之间，咱们更看重正确性。 References[1] 技术写作 第一课: _https://lengrongfu.github.io/... [2] Google开发分档格调指南: _https://developers.google.com... [3] Google绘图: _https://drawings.google.com/_ [4] diagrams.net: _https://diagrams.net/_ [5] lucidchart: _https://www.lucidchart.com/pa...