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