paperbot · PL 论文追踪

全部论文 待读 收藏

P2 Beyond accuracy: assessing software documentation quality

超越准确性:评估软件文档质量
FSE Proceedings of the 28th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering2020匹配度 1/10 · 该论文研究软件文档质量框架与人工评估,不涉及静态分析、LLM/Agent、浮点程序分析或贝叶斯程序分析,与用户研究画像的核心问题基本无关。引用 1 inbox
Christoph Treude, Justin Middleton, Thushari Atapattu
crossref: 2026-09-12

AI 速览

一句话:提出软件文档质量的十维框架,并借技术编辑评估多类文档,发现参考文档与README质量较高而博客问题更多。

软件工程文献中“好”文档的含义一直较为模糊,缺乏清晰的质量界定与评估框架。本文借鉴数据与信息质量社区的工作,提出一个将软件文档质量分解为结构、内容和风格共十个维度的框架。为展示其应用,作者招募技术编辑,使用该框架评估多种软件文档类型的示例,并总结其评估结果:参考文档和 README 文件的质量表现突出,而博客文章存在更多问题。文章还阐述了关于软件文档质量推理的愿景,以及统一质量框架的扩展方向与潜力。

问题
软件工程文献中“好”文档的含义模糊,缺乏清晰的质量界定与评估框架。
方法
借鉴数据与信息质量社区工作,提出包含结构、内容和风格共十个维度的文档质量框架,并招募技术编辑用该框架评估多个软件文档类型的示例。
评估
通过技术编辑对多类文档示例的评估,总结不同文档类型的质量表现,如参考文档和 README 质量突出,博客文章问题更多。
原文摘要(Abstract)

Good software documentation encourages good software engineering, but the meaning of "good" documentation is vaguely defined in the software engineering literature. To clarify this ambiguity, we draw on work from the data and information quality community to propose a framework that decomposes documentation quality into ten dimensions of structure, content, and style. To demonstrate its application, we recruited technical editors to apply the framework when evaluating examples from several genres of software documentation. We summarise their assessments -- for example, reference documentation and README files excel in quality whereas blog articles have more problems -- and we describe our vision for reasoning about software documentation quality and for the expansion and potential of a unified quality framework.

链接与引用

DOI 原文 · PDF(开放获取) ·

BibTeX
@inproceedings{paperbot5714,
  title = {Beyond accuracy: assessing software documentation quality},
  author = {Christoph Treude and Justin Middleton and Thushari Atapattu},
  booktitle = {FSE},
  year = {2020},
  doi = {10.1145/3368089.3417045}
}