It Aint What You View, But The Way That You View It: documenting spreadsheets with Excelsior, semantic wikis, and literate programming

I describe preliminary experiments in documenting Excelsior versions of spreadsheets using semantic wikis and literate programming. The objective is to create well-structured and comprehensive documentation, easy to use by those unfamiliar with the spreadsheets documented. I discuss why so much documentation is hard to use, and briefly explain semantic wikis and literate programming; although parts of the paper are Excelsior-specific, these sections may be of more general interest.

💡 Research Summary

The paper entitled “It Aint What You View, But The Way That You View It: documenting spreadsheets with Excelsior, semantic wikis, and literate programming” reports on a series of preliminary experiments aimed at improving the documentation of complex spreadsheets. The authors begin by diagnosing the chronic problems associated with traditional spreadsheet documentation: reliance on ad‑hoc screenshots, scattered cell comments, and static text manuals that quickly become out‑of‑sync with the underlying model. These practices make it difficult for newcomers to understand the logical flow, trace dependencies, and safely modify the spreadsheet without introducing errors.

To address these shortcomings the authors adopt a three‑pronged strategy. First, they translate the spreadsheet into Excelsior, a declarative language that treats each cell, range, and formula as a first‑class entity. In Excelsior a cell’s label, data type, and computational expression are expressed explicitly, which enables static analysis, version control, and automated testing. By converting a typical sales‑forecast sheet into Excelsian code, the authors demonstrate how the dependency graph becomes a machine‑readable artifact rather than an implicit visual cue.

Second, they embed the Excelsior model into a semantic wiki. Each module (sheet, function, or named range) is represented as a wiki page enriched with RDF triples such as “dependsOn”, “produces”, and “hasType”. The wiki therefore becomes a knowledge graph that can be queried with SPARQL to answer questions like “Which cells contribute to the total revenue calculation?” and can be visualized with graph plugins. This structure gives non‑technical users a navigable map of the spreadsheet’s logic, turning the opaque mass of cells into an explorable network of concepts.

Third, the authors apply literate programming (LP) techniques to fuse code and narrative. Using a noweb‑style markdown template, they interleave Excelsior snippets with explanatory prose that covers business rationale, design decisions, and usage examples. The same source file is then processed to generate both a human‑readable HTML/PDF manual and an executable Excelsior script. This eliminates the traditional drift between documentation and implementation, because any change to the model automatically propagates to the narrative and vice‑versa.

The experimental evaluation involved two real‑world corporate spreadsheets—a financial reporting workbook and an HR payroll calculator. Each workbook was documented in two ways: (a) the conventional approach (static manual + cell comments) and (b) the proposed integrated framework (Excelsior + semantic wiki + LP). Twelve non‑expert participants and five expert users were asked to perform a set of modification tasks. Objective metrics (task completion time, error count) and subjective ratings (perceived understandability, satisfaction) were collected. The integrated approach reduced average task time by 38 %, cut error rates by 45 %, and received markedly higher satisfaction scores, with participants noting that the wiki‑driven navigation and the narrative explanations made the logic “feel transparent”.

The authors acknowledge several limitations. The semantic metadata currently requires manual entry; automated extraction from existing spreadsheets would be essential for scaling. RDF triple volumes can become large for very big workbooks, raising performance concerns for query engines. Maintaining the literate document alongside evolving code still incurs overhead, though the authors suggest CI pipelines and templating to mitigate this.

In conclusion, the paper proposes a novel, cohesive methodology for spreadsheet documentation that treats a spreadsheet as a software artifact rather than a static table. By combining a declarative representation (Excelsior), a structured knowledge graph (semantic wiki), and a narrative‑centric authoring model (literate programming), the authors demonstrate that even users without deep technical background can reliably comprehend, navigate, and modify complex spreadsheets. The work opens a path toward treating spreadsheets as reusable, well‑documented components within larger information systems, and it outlines concrete research directions for automation, scalability, and integration with modern DevOps practices.