Introduction
Technical documentation often faces a common user behavior: readers frequently bypass descriptive text to find concrete examples. Research indicates that up to 76% of users engage in this "example-first" strategy. Despite this, many natural language generation (NLG) systems have historically treated text and examples as separate entities. This paper argues for a unified approach where examples and descriptions are planned together to meet the specific needs of different audiences.
The Categorization Framework
The authors propose that examples cannot be selected in isolation; they must be tailored based on three dimensions: Polarity, Knowledge Type, and Text-Type.
- Polarity: Distinguishes between positive instances, negative instances, and "anomalous" cases (e.g., an edge case that technically fits a definition but appears atypical).
- Knowledge Type: Categorizes whether the subject is a concept, a relation, or a process.
- Text-Type: Differentiates between introductory texts for novices and reference manuals for experts.
Text-Planning and Implementation
The system is built on the Explainable Expert Systems (EES) framework, utilizing a text-planner that constructs discourse trees. The planner uses schematic "plan operators" to achieve communicative goals. For instance, when generating introductory text, the system prioritizes syntactic surface features and intersperses simple examples immediately following the relevant text.
In contrast, for advanced reference material, the system provides a complete internal structural description and clusters complex, multi-feature examples at the end of the section.
Key Insights: Audience-Centric Generation
The research highlights several critical heuristics for effective documentation:
- Contextual Polarity: An example's status as "positive" or "negative" is not inherent but depends on the preceding text. For example, the LISP atom
NILis a positive example of an empty list, but if the text defines lists solely as items within parentheses,NILbecomes an anomalous example requiring further explanation. - Cognitive Load Management: For beginners, the "one feature at a time" rule is paramount. Examples should be simple and focused. If complexity is unavoidable, the system must generate "prompts" to guide the reader's attention.
- Expert Density: Advanced users prefer "dense" examples that demonstrate the interaction of multiple features simultaneously, allowing for a more comprehensive understanding with fewer total examples.
Results and Evaluation
Using LISP programming as a testbed, the authors analyzed existing human-written manuals—specifically Touretzky’s LISP: A Gentle Introduction and Guy Steele’s Common Lisp: The Language—to derive their heuristics. They demonstrated that their system could generate distinct outputs from the same knowledge base. The introductory output focused on visible syntax (parentheses) and simple data pairs, while the advanced output utilized recursive definitions and provided a single, complex example block showcasing symbols, floating-point numbers, and nested lists.
Conclusion and Future Directions
While the framework successfully differentiates between broad categories like "introductory" and "reference," the authors note that future work should incorporate more nuanced linguistic typologies. Additionally, while the system's architectural capabilities are proven, formal user studies are needed to measure the actual impact on human comprehension across various domains, such as medicine or law.
Summary updated