How good is your documentation?
QueenyJin opened this issue · comments
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?
先开个头,我突然想起《Don't Make Me Think》还是哪里有过这样的一句话:用户是带着问题来到我们的网站,他们只关注于如何解决他们的问题。
所以,我觉得如果要设计针对于文档的度量,那么它应该是以快速解决用户的问题为出发点。对应的度量方式,需要从多个维度来考虑,诸如于:用户在哪里遇到问题,诸如 bug,那么他们将如何解决:
- 如果是通过文档的话,那么我们可以:在错误信息里,提供文档的链接。如以错误码的形式,以链接到 GitHub issue 的形式。
- 如果通过的是搜索引擎的话,那么我们需要提炼一些关键字作为相关文章的标题。诸如于Azure Cli 的安装示例。