教程类文档撰写的问题
教程类文档
教程类文档的含义与其名字一致，是用来【指导客户实践】的文档。其内容应该尽可能的简单、易懂，这样读者更容易理解，文档的【指导性】更好。
从撰写者角度寻找问题
不同的厂家都会有自己的一些教程文档，这些文档描述了产品的功能，指导用户使用产品的方法或步骤等。虽然这些文档多如牛毛，可当读者真正按照这些文档去操作时，可能执行到某一步骤就再也走不下去。这之后要不放弃，要不就需要寻求厂家支持。
造成这类问题的原因可以说有部分是读者自身的问题。读者的水平参差不齐是一个现实情况，但是不应该以这个理由为糖衣炮弹来反击别人对文档内容提出的质疑。
读者的水平可以说是一种不可控因素，这种因素应该考虑却不应该被过度夸大。基于这样的论述，我在这里谈谈文档撰写者存在的一些问题。
先入为主的思维
在撰写教程类文档之前，撰写者自己应该已经非常熟悉所要描述的对象。这样的熟悉度对于文档的内容有非常重要的意义，不过也可能导致一些【先入为主】的问题。
这里提到的【先入为主】指的是文档撰写者会将操作过程中的一些步骤当做是已经具备的条件，而不加以具体描述。这样的问题，撰写者自己很难发现，可读者却可能会在这里遇到障碍。
有些教程中会有一些【一次性】的操作。所谓【一次性】是表示只需执行一次即可，例如安装一些必要的驱动，第一次安装后你再重新配置时不用再重新安装。这样很可能会让撰写者【先入为主】的以为这个驱动的安装是已经具备的条件，在文档中不会详细描述。
当读者按照文档中的描述一步步操作之后，可能会忽略驱动安装这一步骤，而缺少了必要的驱动，将会导致硬件无法正常工作。即便一些聪明的读者根据最后的现象意识到了这个问题，可是他们又该从哪里去找驱动呢？即便找到了又该安装那个版本呢？
另一个类似的问题是撰写者对于描述内容中自己觉得非常简单的内容不会详细描述，可能仅仅一笔带过。
对于撰写者来说，他自己有着丰富的经验，在多次的操作之后对于一些过程他会觉得非常简单。这样的判断可能会让他在文档的撰写过程中不太注重描述那些自己眼中非常简单的过程。可是读者是否具备与撰写者相同的经验呢？可能大多数时间内读者都不具备这样的条件吧！那么这些被撰写者简单描述的过程就可能成为读者的【障碍】。
没有感觉上那样浅显易懂
许多作者对自己作品的认识不够准确，可能会存在【过度自信】的问题。作者自己认为文档非常浅显易懂，可实际情况却不一定与他的想法一致。实际上如果在撰写文档的过程中笔者没有注意这个问题，那么浅显易懂就很可能只是【感性的认识】而已。
使用的一些外部工具未详细描述
在文档中常常要描述操作过程中可能会用到的一些其它工具。一些笔者在文档中对于这些工具的安装可能没有任何说明，在他们看来这些工具应该是读者需要自行解决的问题，不过也可能是出于篇幅考虑。无论是怎样的原因，这样的过程在我看来都是【不合理】的。
之前我在搭建一家公司的芯片开发环境时就遇到了类似的问题。他们的手册中描述需要执行 【xxx.exe】 这个程序来安装必要的驱动，可文档中对这个程序没有任何具体的描述，我就在他们提供的压缩包中找这个程序，结果发现根本就没有，这让我一度怀疑我没有拿到完整的资料。这之后我没有立刻反馈这个问题，我尝试先搜索一下看看，结果就发现可以直接从网上下载到这个程序来使用，这个问题得到了解决。
虽然问题最后得到了解决，但是耗费的时间稍微有点长。其实这个问题完全可以避免，可能只需要在文档中放一个【链接】或者说明一下需要读者【自行搜索安装】就可以了，这又能耗费多少功夫、占用多少版面呢？
前面的问题可以归结为怎么【安装工具】的问题，可其实该安装哪个【版本】的工具也是一个问题。
许多作者在撰写文档时没有具体说明需要安装什么版本的工具，这在读者看来好像就意味着版本根本【不重要】，安装一个就可以了，可实际的情况并非如此。
拿 linux 来说。当你要在 linux 上搭建一套环境时，如果需要使用其它的包，一定要考虑到【版本】的问题。这个【版本】往大了说就是【发行版的版本】，小了说就是【工具的版本】。不同的版本间在很多时候并没有【兼容性】保障，这样当读者安装了不同版本的工具就可能会出现问题，最终很有可能导致环境搭建失败！
逻辑不清楚
逻辑不清楚这个问题不仅仅局限于教程类文档，应该说它是【所有类型】的文档都可能存在的问题。
逻辑不清楚表现在文档上就是内容没有一个清晰的思路，【组织混乱缺乏条理】。这个问题与作者自身的写作功底直接相关，却也深受环境的影响。一些人可能从文档撰写开始到结束都不太清楚自己要写些什么，一些人可能知道自己要写些什么却没有太多的时间去构思，还有一些人可能对演绎推理、归纳总结这些横向纵向的写作技巧没有很好的掌握等等。
写作能力欠缺的作者，可以去看看《金字塔原理》这本书。没有时间的作者还是先把时间留出来吧！要知道一个真正能够指导人们【实践】的文档一定会节省许多时间，不过却并不一定会以你期待的方式表现出来！
大段文字堆叠
一些作者特别喜欢大段大段文字叙述。我曾经也非常喜欢这样的方式，因为我觉得这样才能体现出我的写作才能。其实这样并没有错，只是【不太适合】教程类文档，也许更适合写些散文、随笔等！
这里存在的问题是作者对于自己将要撰写的文档【类别】没有基本的认识。
要知道不同的文档类别需要使用的方法与技巧是不同的。在教程类文档中大段大段的堆叠文字真的不如多放点操作步骤截图，并且将关键步骤在截图中进行标注，这样更直观，更易于读者对比操作！
对于可能存在的坑没有描述
描述整个操作流程是整个文档的核心，可对于一些常见的【坑】也需要进行描述，对于这一点许多作者没有太过重视。
对于操作过程中存在的一些【坑】，作者自己应该深有体会，可是在文档撰写过程中他们却不一定会加以描述。实际上这些【坑】对于所有读者而言是【共享的】，这意味他们也有可能遇到你曾经遇到的问题。如果读者遇到了问题就能够在你的文档中找到解决方案，那么他们操作起来就会相对容易，也不用再重新踏你曾经踏过的坑！不过需要注意的是限于篇幅与环境，你可能无法做到面面俱到，描述常见问题的解决方案即可！
总结
最近我在阅读一些教程类文档时遇到了一些问题，对这些问题的思考让我对文档撰写者存在的一些问题有了更深入的体会，在这里写下这些体会与自己的思考，希望能为以后撰写文档提供一些指导！