Support for Long-Form Documentation Authoring and Maintenance
Amber Horvath, Andrew Macvean, Brad A. Myers · 2023
When creating a software project of any significant size or complexity, developers must write about the code in some form. While this is a common practice, tooling support for creating, and perhaps more significantly, maintaining these documents remains limited, despite these documents benefiting later users of the corresponding code. In order to combat some of these known challenges, we developed Sodalite – a context-aware, Visual Studio Code extension for writing and maintaining code-related documents. Sodalite represents a holistic approach to the documentation authoring, maintaining, and using life cycle by suggesting relevant code to attach to the document using common code-writing templates, evaluating how up-to-date the document is using the code in the editor, automatically attempting to identify out-of-date information, and, based on how successful the system is, notifying the user of how trustworthy the document seems to be given their version of the related code. In our preliminary evaluation of Sodalite, we found that users of the system were able to successfully author documents about their code and the system's out-of-date link checking was accurate 86.5% of the time.