[Paper Review] Do we really need to write documentation for a system? CASE tool add-ons: generator+editor for a precise documentation

Maria Spichkova, Xiuna Zhu+1 more|arXiv (Cornell University)|Apr 29, 2014

Advanced Software Engineering Methodologies12 references4 citations

TL;DR

This paper proposes an integrated solution within the AutoFocus CASE tool that automatically generates and edits formal FOCUS specifications from system models, ensuring documentation stays synchronized with design changes. By combining a model-driven specification generator with a template-based FOCUS editor, the approach reduces manual effort and enhances maintainability of formal system documentation.

ABSTRACT

One of the common problems of system development projects is that the system documentation is often outdated and does not describe the latest version of the system. The situation is even more complicated if we are speaking not about a natural language description of the system, but about its formal specification. In this paper we discuss how the problem could be solved by updating the documentation automatically, by generating a new formal specification from the model if the model is frequently changed.

Motivation & Objective

• Address the widespread problem of outdated system documentation in software development projects.
• Solve the challenge of keeping formal specifications synchronized with evolving system models.
• Improve usability and adoption of formal methods by reducing the cognitive and time burden on engineers.
• Provide a practical, tool-supported methodology for generating and editing precise formal documentation.
• Integrate human-centered design principles into formal specification to enhance readability and maintainability.

Proposed method

• Extend the AutoFocus 3 CASE tool with a formal specification generator that derives FOCUS specifications from model elements.
• Use an assumption/guarantee style specification format to express component behavior based on model semantics.
• Generate LaTeX-formatted FOCUS specifications using pre-defined templates for consistent, human-readable output.
• Implement a dedicated FOCUS editor with syntax highlighting, code folding, and a toolbox for FOCUS operators and frames.
• Support both graphical and plain-text representation of composite component specifications for flexibility.
• Enable manual editing and optimization of generated specifications while preserving formal correctness and structure.

Experimental results

Research questions

• RQ1 How can formal system documentation be kept up to date when system models evolve frequently?
• RQ2 What tool support is needed to make formal specification generation and editing practical for engineers?
• RQ3 To what extent can human factors be integrated into formal specification languages to improve usability?
• RQ4 Can automated generation of formal specifications reduce the effort and error rate in system documentation?
• RQ5 How can a balance be achieved between formal precision and readability in system specifications?

Key findings

• The proposed generator produces formal FOCUS specifications directly from AutoFocus models, ensuring documentation reflects the latest system state.
• The integrated FOCUS editor supports syntax checking, code folding, and template-based editing, significantly improving maintainability of formal specs.
• Generated specifications are structured in an assumption/guarantee style, enhancing clarity and facilitating verification.
• The toolchain allows both automatic generation and manual refinement of specifications, supporting iterative development and reuse.
• The approach enables integration with formal verification tools like Isabelle/HOL, supporting semi-automatic proof construction.
• The solution reduces the effort of writing and maintaining formal documentation, making formal methods more accessible to practitioners.