How good is your documentation?
QueenyJin opened this issue · 1 comments
QueenyJin commented
What would be the metrics of high-quality documentation? From what we can learn from Developing Quality Technical Information, it would be: Easy to use, Easy to find, and Easy to understand. Then what would be the metrics that matter?
phodal commented
先开个头，我突然想起《Don't Make Me Think》还是哪里有过这样的一句话：用户是带着问题来到我们的网站，他们只关注于如何解决他们的问题。
所以，我觉得如果要设计针对于文档的度量，那么它应该是以快速解决用户的问题为出发点。对应的度量方式，需要从多个维度来考虑，诸如于：用户在哪里遇到问题，诸如 bug，那么他们将如何解决：
- 如果是通过文档的话，那么我们可以：在错误信息里，提供文档的链接。如以错误码的形式，以链接到 GitHub issue 的形式。
- 如果通过的是搜索引擎的话，那么我们需要提炼一些关键字作为相关文章的标题。诸如于Azure Cli 的安装示例。