Building Knowledge Bases for the Generation of Software Documentation

Cecile Paris, Keith Vander LindenCOLING 1996

TL;DR

Generating software documentation automatically is challenging because it requires a detailed knowledge base that's hard to build. This paper introduces DRAFTER, a tool that helps technical authors create user-centered documentation by automatically extracting parts of the necessary knowledge base from software interface design tools, significantly reducing manual effort.

What Problem Does This Paper Address?

Automated text generation, particularly for software documentation, is a promising field. However, a major hurdle is the creation of the underlying knowledge base (KB) that fuels these systems. Traditionally, these KBs are built manually, which is time-consuming and expensive. This paper tackles the problem of efficiently building KBs for software documentation by exploring how to automatically acquire parts of this knowledge from existing software interface design tools. The goal is to make automated documentation generation more practical and cost-effective.

Methods

The core of the DRAFTER system lies in its ability to leverage information from software interface design tools. Specifically, it uses design specifications (like those from VisualWorks) to automatically derive "task model instances" for windows, dialog boxes, and widgets. This includes inferring basic interface actions (e.g., clicking a button, opening a window). These automatically generated building blocks then form the foundation of a richer, user-centered task model. Technical authors can then augment this automatically derived information using DRAFTER's authoring interface, which supports controlled natural language and graphical representations to define higher-level goals, preconditions, and other procedural relationships. The system then uses this complete task model to generate multilingual documentation (English and French).

Datasets

Not discussed in the paper. The paper focuses on a methodology and a tool, using an example application (a visual works mock-up of a word processing application) for illustration rather than formal dataset evaluation.

Key Insights and Ideas

  • Bridging Design and Documentation: The paper highlights a crucial insight: the information needed for user-centered documentation often already exists, implicitly or explicitly, within software interface design tools. By tapping into this, we can automate a significant portion of KB construction.
  • User-Centeredness through Task Models: The authors emphasize that effective documentation isn't just about describing interface elements but about explaining why a user would perform an action (task-oriented help). Their approach uses hierarchical task models to capture these user goals and sub-goals.
  • Reducing Authoring Burden: The automatic acquisition of basic interface actions and objects from design tools dramatically simplifies the technical author's job. Instead of building everything from scratch, they can focus on higher-level task definition and refinement.
  • Multilingual Generation: The system's ability to generate documentation in multiple languages (English and French) from a single knowledge base is a significant practical advantage.

Key Results

The paper demonstrates that DRAFTER can automatically acquire a substantial portion of the necessary building blocks for a task model from interface design specifications. In their example, seven out of nine actions in a procedural structure were automatically specified, leaving the author to define only the main user goal and three plan nodes. This significantly reduces the manual effort required for knowledge base construction. The system successfully generates multilingual drafts of instructions, as shown in Figure 4.

Limitations and Future Work

The authors acknowledge that the automatically acquired instances do not represent all possible information that could be derived. They are actively investigating ways to make more design knowledge accessible and understandable to technical authors. Future work includes exploring tighter integration between the design and documentation processes, potentially involving individuals working collaboratively during the design phase. They also plan to evaluate the system with technical authors to further refine its usability and marketability.

Summary updated

BibTeX
@inproceedings{paris1996building,
  author = {Cecile Paris and Keith Vander Linden},
  title = {{Building Knowledge Bases for the Generation of Software Documentation}},
  booktitle = {International Conference on Computational Linguistics},
  year = {1996},
}

Loading related content...

Figure