Introduction

DEFT, the Develop Environment For Tutorials, is a tool for the creation and maintenance of documentation which is partly handwritten and partly generated. Usually documentation is either completely generated or completely handwritten. Both approaches have their drawbacks. While generated documentation can be easily updated by a simple regeneration, any manual changes that might have been performed are lost. Completely handwritten documentation, on the other hand, needs a lot of effort to be kept up to date. Furthermore, it is easy to introduce inconsistencies.

DEFT allows the creation and maintenance of documentation which is primarily handwritten, but has "islands" of generated content. These islands can be regenerated if necessary. The surrounding handwritten content is not affected.

DEFT supports the generation of code listings from Java code, model listings from Ecore models, images from Ecore diagrams, and more. When any of the underlying artifacts (code, models, ...) are changed, the built-in guidance module informs you and you can decide whether to regenerate the affected document content. All changes are recorded and can be reviewed in order to check whether the generated content still looks as expected. Furthermore, the enumeration of all changes helps you to identify the location of outdated handwritten content, because usually text close to regenerated content must also be updated.

The screenshot shows DEFT in action. On the left side is the Project View which lets you create and manage chapters (files with handwritten content) and artifacts (Java code, Ecore models, ...). In the center is the chapter editor which contains both handwritten and generated content. In the lower part is the Task View with consistency hints.

Screenshot of DEFT