The documentation of API functions typically conveys detailed specifications for the benefit of interested readers. In some cases, however, it also contains usage directives, such as rules or caveats, of which authors of invoking code must be made aware to prevent errors and inefficiencies. There is a risk that these directives may be ldquolostrdquo within the verbose text, or that the text would not be read because there are so many invoked functions. To address these concerns for Java, an Eclipse plug-in named eMoose decorates method invocations whose targets have associated directives. Our goal is to lead readers to investigate further, which we aid by highlighting the tagged directives in the JavaDoc hover. We present a lab study that demonstrates the directive awareness problem in traditional documentation use and the potential benefits of our approach.

Comprehending an unfamiliar code fragment requires an awareness of explicit usage directives that may be present in the documentation of some invoked functions. Since it is not practical for developers to thoroughly investigate every call, directives may be missed and errors may occur. We previously reported on a tool called eMoose, which highlights calls to methods with associated directives, and on a controlled comparative lab study in which eMoose users were more successful at fixing bugs in given code fragments. In this paper we attempt to shed light on the factors behind these differences with a detailed analysis of videos from the study. We argue that information foraging theory may explain the subjects' reading choices and the impact of our tool. We also suggest ways to structure documentation to increase the prospects of knowledge acquisition.

Recent techniques show the benefits of attaching community generated knowledge to artifacts in an information space and presenting it to subsequent readers. We argue that such knowledge may also be relevant to the readers of artifacts which link to this target. Such situations are particularly frequent in software development, where a lack of awareness of critical directives associated with an invoked function can lead to costly errors. We describe how eMoose, a group memory-aid for this domain, addresses these problems by visually "pushing" annotated knowledge from invocation targets into the invoking code. Similar techniques could potentially be applied to other development phases and to other domains.

Software designers in the object-oriented paradigm can make use of modeling tools and standard notations such as UML. Nevertheless, casual observations from collocated design collaborations suggest that teams tend to use physical mediums to sketch a plethora of informal diagrams in varied representations that often diverge from UML. To better understand such collaborations and support them with tools, we need to understand the origins, roles, uses, and implications of these alternate representations. To this end we conducted observational studies of collaborative design exercises, in which we focused on representation use. Our primary finding is that teams intentionally improviserepresentations and organize design information in responseto ad-hoc needs, which arise from the evolution of the design, and which are difficult to meet with fixed standard notations. This behavior incurs orientation and grounding difficulties for which teams compensate by relying on memory, other communication mediums, and contextual cues. Without this additional information the artifacts are difficult to interpret and have limited documentation potential. Collaborative design tools and processes should therefore focus on preserving contextual information while permitting unconstrained mixing and improvising of notations.