Guides Assistant for Creating Task Documentation (hereafter referred to as "Guides Assistant") is a set of Eclipse plug-ins that allow developers to create documentation simply by pointing out elements in the software system that are important for a particular task and providing active assistance to developers using the documentation. The plug-ins focus on software artifacts and their relationships, which are the everyday focus of developers.

Guides Assistant reduces the time it takes to document a software system. The tool also improves productivity when performing documented tasks by providing active assistance, allowing developers to use or modify a particular program feature more quickly than by following traditional forms of documentation. This increased productivity can improve collaboration in both local and geographically dispersed teams.

The tool creates documentation in the form of guides, which encapsulate passive information about important tasks along with active steps to be followed. The approach is "concern-based" and introduces active steps into traditionally passive concerns. Developers can begin by creating a concern that identifies elements of importance in the context of a task, which, we believe, is easier and more natural than trying to formulate a process up front. They can then easily create and export a guide based on this concern.

Other developers can follow the guide and are provided with interactive support. As the developers progress in the guide, their results are recorded as examples for future reference. Guides are particularly suited for agile teams because they are closely tied to the code and can be quickly created and modified. Guides Assistant also contains a feature called XFinder for locating examples that were not created by following a guide.

This tool runs on Windows® and Linux®. The package includes the set of plug-ins and documentation.

How does it work?

Guides Assistant is tightly integrated within the Eclipse development environment and allows developers to create documentation simply by pointing out elements in the software system that are important for a particular task; these elements constitute a concern. Elements include classes, methods, extension points, files, and even Web pages. From these elements, a guide for the task with an appropriate step for each element is created. For example, if the user selects the XYZ interface as an important element, an "Implement XYZ interface" step is created and represented in a concern model.

After a step is created, comments and references to other artifacts can be added to provide contextual information. The resulting guide also provides interactive support to the end user. For example, when the user performs the "Extend XYZ class" step by double-clicking on it, the "Create new class" wizard in Eclipse is launched.

Barthélémy Dagenais is a Ph.D. student at McGill University in Montréal and a part-time researcher at IBM T.J. Watson Research Center (through IBM Canada). He completed his master thesis under the supervision of Prof. Martin Robillard on the dual topic of framework evolution and static analysis of partial programs. At IBM, Mr. Dagenais works with Harold Ossher on easing the creation and usage of framework documentation through a concern-oriented tool set.

Harold Ossher is a researcher at the IBM Thomas J. Watson Research Center. He is one of the originators of subject-oriented programming, multi-dimensional separation of concerns and Hyper/J, and prototype support for agile requirements management on Jazz. Dr. Ossher is currently working on tool support for pre-requirement information gathering and organization; he is also working on support for effective information exchange among developers.