阅读文档的最大优势是您经常会在那里找到答案，而您需要做的是潜入文档并自己找到它。
随着工作的开展您会发现越来越多的问题没有现成的教程。
本文从 JavaScript 开发者、讲师 Marcin Wosinek 的视角与您分享了一个开发者如何定义好技术文档。
如果您提出可以通过文档快速回答问题，人们的反应将取决于您提出问题的地方的气氛、与您合作的团队或在线论坛。友好的技术文档会为您提供可以找到答案的链接。不太友好的技术文档会为您提供“阅读*咳嗽***友好*手册——或者给您一个链接，或者让您自己百度搜索一下。应该尽量避免出现这种情况。让我们看看如何培养阅读文档的技能！
使用文档
最重要的是，当您遇到困难时，请开始尝试从文档中获取答案。
在文档中找到您问题的答案
大多数文档都比较枯燥，旨在提供答案，而且阅读起来不一定很有趣。在寻找问题的解决方案时更容易专注于它。我讨厌阅读文档来了解项目。无论是我开始的新项目还是我正在学习的图书馆都没有关系。这感觉像是在浪费时间，因为我没有上下文，而且很难理解我正在阅读的内容之间的联系。相反，我会尝试自己做一些事情，失败，然后回到文档中寻找答案。在那种情况下，我至少知道我不知道的东西，而且我热衷于弥合差距。
在寻找问题的解决方案时更容易专注于文档
在文档中使用搜索工具
当您有问题需要解决时，您可以使用搜索工具快速获取相关信息。对于第三方库，您可以利用搜索引擎将搜索限制在项目网站上，方法是添加site:
您可以通过添加 site:
使用百度、 Google、Bing 和 DuckDuckGo 也一样。对于代码内的文档，您可以使用与搜索代码库相同的工具：
- 编辑器内搜索
- ripgrep
- 或者git grep
一个例子git grep：
$ git grep 'http.post'
src/auto/injector.js: * $http.post(trackingUrl, trackedEvents);
src/ng/http.js: * $http.post('/someUrl', data, config).then(successCallback, errorCallback);
src/ng/http.js: * - {@link ng.$http#post $http.post}
搜索文档有几个好处：
- 您可以熟悉文档结构
- 您将找到与您的主题相关的文档的所有部分
图片描述
API 参考 - 方法的枯燥描述
图片描述
教程或指南——它提供了更多的上下文。
如果您不了解文档，请不要担心
文档质量差异很大。通常它是一个非常容易访问的文档。可能是假设读者具有一些系统知识，但文本中没有明确说明。这让新人有些失落。那些私有的商业项目文档问题可能最多。如果您有一个小团队同时维护代码库及其文档，那么任何新加入项目的人员都可能需要几个月的时间来浏览文档并尝试理解它。
开源项目的文档通常稍好一些。没有良好文档的项目不太可能成功。
不要跳过指南
如果项目提供了教程或指南，最好查看一下。如果您经常遇到类似的问题，只需找到涵盖该问题的指南部分并仔细阅读即可。一份完整的指南将为您提供理解您正在使用的机制所需的上下文。
不要跳过文档中的指南
深入了解 API 的相关部分
API 描述的是最技术性的文档。通常，它非常枯燥，缺乏对可以使用给定方法的上下文的良好概述。它向您展示了您可以使用的所有类、方法、参数和输出。
API 的描述最有技术性
如果可用，请仔细阅读对相同或相似事物的不同描述。通常第一种方法是参考其他方法——因此，如果您在阅读第一种方法后仍然困惑，那么您可以检查其他人的文档是否使其更清晰。
结果
凭借这些方法，您将改变对象的内部状态或获得一些输出。一本 API 指导手册应该很好地描述两者。
输入变化
通常，方法是接受许多参数组合的输入。文档将向您展示获取所需内容的所有选项。
关于文档的最终想法
阅读文档是一项重要的技能，您只能通过练习来学习。当您第一次尝试时，不要气馁，随着时间的推移它会变得更好。
镭内容写管用平台，如下图示，有效解决了上述挑战，确保您交付用户友好的技术手册。
简洁文档中心入口
过滤分类，免除查找烦恼
跨手册和手册内部全文搜索，让内容一览无余
如果您期望获取“用户友好”的文档，请联系我们。
