Guidance through active concerns

Producing usable documentation has always been a tedious task, and even communicating important knowledge about a system among collaborators is difficult. This paper describes an approach to creating 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. A developer 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. S/he can then easily create a guide to the task based on this concern, and export it. Other developers can follow the guide, and, as they do so, their results are recorded as examples for future reference. As an early step towards validation, we created a guide for the complex task of creating an Eclipse editor.