As computer systems grow ever larger and more complex, a crucial task in software development is for one person (the system expert) to communicate to another (the system novice) how a certain program works. This paper reports on the author's experiences with a paradigm for program documentation that we call literate tracing. A literate trace explains a software system using annotated, concrete execution traces of the system. Literate traces complement both in-code comments (which often lack global context) and out-of-band design docs (which often lack a concrete connection to the code). We also describe TReX, our tool for making literate traces that are interactive, visual, and guaranteed by construction to be faithful to the program semantics. We have used TReX to write literate traces explaining components of large systems software including the Linux kernel, Git source control system, and GCC compiler.

翻译：随着计算机系统日益庞大与复杂，软件开发中的关键任务之一在于系统专家向系统新手阐释特定程序的运行机制。本文报告了作者在程序文档范式——我们称之为"Literate Tracing"（可读化追踪）——方面的实践经验。可读化追踪通过带有注释的、具体的系统执行轨迹来解释软件系统。该范式既补充了代码内注释（通常缺乏全局上下文），也弥补了独立设计文档（往往与代码缺乏具体关联）的不足。本文同时介绍了TReX工具，该工具能够构建具有交互性、可视化特性且通过构造保证符合程序语义的可读化追踪文档。我们已运用TReX为包括Linux内核、Git版本控制系统及GCC编译器在内的大型系统软件组件撰写了可读化追踪文档。