Introduction

Here you will learn what DEFT is all about, how it can help you with tutorial writing and maintenance and what its features are.

The idea behind DEFT

When a new version of a framework (or a software library) is released, extensive documentation is important for the programmers to use it as intended. One type of documentation is the so-called tutorial, which is here understood as explanations how to solve a given programming task. The tutorial consists of both text and code examples which together should provide a clear picture to the developer how different classes and methods must work together.

Tutorials are usually accompanied by an example program which uses a number of the framework's functionality. Explanatory text is written and manually enriched with code snippets if appropriate. However, at some point in time the framework is going to evolve, probably having its API changed and therefore breaking existing applications, including the example from the tutorial.

The standard solution for this is to update the example program and then find all source code examples in the tutorial that are different from the new version of example program. These code examples are then manually replaced and the surrounding tutorial text is proofread to make sure that the code snippets and the text are consistent. This is a tedious and error-prone task, especially for long tutorials. As a consequence, the quality of the tutorial often decreases or the tutorial is not maintained at all.

With DEFT tutorial maintenance becomes a little easier. DEFT comes with an integrated editor and a code repository, into which the example code must be imported. Fragments of the code can be added to the tutorial text easily via drag&drop. Internally references to the according parts of the code files are created, but the documentation writer won't see any of that.

When the framework evolves, the tutorial must be updated. The first step is the same as in the manual process: make the example program work again with the new framework version. The updated example program is then imported into DEFT, which causes all source code references to be reevaluated on the new code, so the code samples are immediately updated. Of course, some changes might be so big that unwanted code is displayed or that the code reference even points to "nowhere". For that reason all code snippets that have changed during the update are are recorded and presented to the documentation writer. So he knows exactly which of them to check (and which need no examination). There is also less text to be proofread, as usually only the text around changed code snippets must be revised.

Features of DEFT

While DEFT is still in its infancy, it already has some useful features.