Extended Version of Elucidative Development for Model-Based Documentation and Language Specification

Documentation is an essential activity in software development, for source code as well as modelling artefacts. Typically, documentation is created and maintained manually which leads to inconsistencies as documented artefacts like source code or models evolve during development. Existing approaches like literate/elucidative programming or literate modelling address these problems by deriving documentation from software development artefacts or vice versa. However, these approaches restrict themselves to a certain kind of artefact and to a certain phase of the software development life-cycle. In this paper, we propose elucidative development as a generalisation of these approaches supporting heterogeneous kinds of artefacts as well as the analysis, design and implementation phases of the software development life-cycle. Elucidative development allows for linking source code and model artefacts into documentation and thus, maintains and updates their presentation semi-automatically. We present DEFT as an integrated development environment for elucidative development. We show, how DEFT can be applied to language specifications like the UML specification and help to avoid inconsistencies caused by maintenance and evolution of such a specification

Creating and Maintaining Consistent Documents with Elucidative Development

Software systems usually consist of multiple artefacts, such as requirements, class diagrams, or source code. Documents, such as specifications and documentation, can also be viewed as artefacts. In practice, however, writing and updating documents is often neglected because it is expensive and brings no immediate benefit. Consequently, documents are often outdated and communicate wrong information about the software. The price is paid later when a software system must be maintained and much implicit knowledge that existed at the time of the original development has been lost. A simple way to keep documents up to date is generation. However, not all documents can be fully generated. Usually, at least some content must be written by a human author. This handwritten content is lost if the documents must be regenerated. In this thesis, Elucidative Development is introduced. It is an approach to create documents by partial generation. Partial generation means that some parts of the document are generated whereas others are handwritten. Elucidative Development retains manually written content when the document is regenerated. An integral part of Elucidative Development is a guidance system, which informs the author about changes in the generated content and helps him update the handwritten content.:1 Introduction 1.1 Contributions 1.2 Scope of the Thesis 1.3 Organisation 2 Problem Analysis and Solution Outline 2.1 Redundancy and Inconsistency 2.2 Improving Consistency with Partial Generation 2.3 Conclusion 3 Background 3.1 Grammar-Based Modularisation 3.2 Model-Driven Software Development 3.3 Round-Trip Engineering 3.4 Conclusion 4 Elucidative Development 4.1 General Idea and Running Example 4.2 Requirements of Elucidative Development 4.3 Structure and Basic Concepts of Elucidative Documents 4.4 Presentation Layer 4.5 Guidance 4.6 Conclusion 5 Model-Driven Elucidative Development 5.1 General Idea and Running Example 5.2 Requirements of Model-Driven Elucidative Development 5.3 Structure and Basic Concepts of Elucidative Documents in Model-Driven Elucidative Development 5.4 Guidance 5.5 Conclusion 6 Extensions of Elucidative Development 6.1 Validating XML-based Elucidative Documents 6.2 Backpropagation-Based Round-Trip Engineering for Computed Text Document Fragments 6.3 Conclusion 7 Tool Support for an Elucidative Development Environment 7.1 Managing Active References 7.2 Inserting Computed Document Fragments 7.3 Caching the Computed Document Fragments 7.4 Elucidative Document Validation with Schemas 7.5 Conclusion 8 Related Work 8.1 Related Documentation Approaches 8.2 Consistency Approaches 8.3 Compound Documents 8.4 Conclusion 9 Evaluation 9.1 Creating and Maintaining the Cool Component Specification 9.2 Creating and Maintaining the UML Specification 9.3 Feasibility Studies 9.4 Conclusion 10 ConclusionSoftwaresysteme setzen sich üblicherweise aus vielen verschiedenen Artefakten zusammen, zum Beispiel Anforderungen, Klassendiagrammen oder Quellcode. Dokumente, wie zum Beispiel Spezifikationen oder Dokumentation, können auch als Artefakte betrachtet werden. In der Praxis wird aber das Schreiben und Aktualisieren von Dokumenten oft vernachlässigt, weil es zum einen teuer ist und zum anderen keinen unmittelbaren Vorteil bringt. Dokumente sind darum häufig veraltet und vermitteln falsche Informationen über die Software. Den Preis muss man später zahlen, wenn die Software gepflegt wird, weil viel von dem impliziten Wissen, das zur Zeit der Entwicklung existierte, verloren ist. Eine einfache Möglichkeit, Dokumente aktuell zu halten, ist Generierung. Allerdings können nicht alle Dokumente generiert werden. Meist muss wenigstens ein Teil von einem Menschen geschrieben werden. Dieser handgeschriebene Inhalt geht verloren, wenn das Dokument neu generiert werden muss. In dieser Arbeit wird das Elucidative Development vorgestellt. Dabei handelt es sich um einen Ansatz zur Dokumenterzeugung mittels partieller Generierung. Das bedeutet, dass Teile eines Dokuments generiert werden und der Rest von Hand ergänzt wird. Beim Elucidative Development bleibt der handgeschriebene Inhalt bestehen, wenn das restliche Dokument neu generiert wird. Ein integraler Bestandteil von Elucidative Development ist darüber hinaus ein Hilfesystem, das den Autor über Änderungen an generiertem Inhalt informiert und ihm hilft, den handgeschriebenen Inhalt zu aktualisieren.:1 Introduction 1.1 Contributions 1.2 Scope of the Thesis 1.3 Organisation 2 Problem Analysis and Solution Outline 2.1 Redundancy and Inconsistency 2.2 Improving Consistency with Partial Generation 2.3 Conclusion 3 Background 3.1 Grammar-Based Modularisation 3.2 Model-Driven Software Development 3.3 Round-Trip Engineering 3.4 Conclusion 4 Elucidative Development 4.1 General Idea and Running Example 4.2 Requirements of Elucidative Development 4.3 Structure and Basic Concepts of Elucidative Documents 4.4 Presentation Layer 4.5 Guidance 4.6 Conclusion 5 Model-Driven Elucidative Development 5.1 General Idea and Running Example 5.2 Requirements of Model-Driven Elucidative Development 5.3 Structure and Basic Concepts of Elucidative Documents in Model-Driven Elucidative Development 5.4 Guidance 5.5 Conclusion 6 Extensions of Elucidative Development 6.1 Validating XML-based Elucidative Documents 6.2 Backpropagation-Based Round-Trip Engineering for Computed Text Document Fragments 6.3 Conclusion 7 Tool Support for an Elucidative Development Environment 7.1 Managing Active References 7.2 Inserting Computed Document Fragments 7.3 Caching the Computed Document Fragments 7.4 Elucidative Document Validation with Schemas 7.5 Conclusion 8 Related Work 8.1 Related Documentation Approaches 8.2 Consistency Approaches 8.3 Compound Documents 8.4 Conclusion 9 Evaluation 9.1 Creating and Maintaining the Cool Component Specification 9.2 Creating and Maintaining the UML Specification 9.3 Feasibility Studies 9.4 Conclusion 10 Conclusio

C# Traceability System

Traceability information is a valuable asset that software development teams can leverage to minimise their risk during production and maintenance of software projects. When maintainers are added to a software project post-production, they have to learn the system from scratch and understand its dynamics before they can begin making appropriate modifications to the source code. The system outlined in this paper extracts traceability information directly from the source code of C# projects, and presents it in such a way that it can be easily used to understand the logic and validate changes to the system

Leveraging Program Comprehension with Concern-oriented Source Code Projections

In this paper we briefly introduce our concern-oriented source code projections that enable looking at same source code in multiple different ways. The objective of this paper is to discuss projection creation process in detail and to explain benefits of using projections to aid program comprehension. We achieve this objective by showing a case study that illustrates using projections on examples. Presented case study was done using our prototypical tool that is implemented as a plugin for NetBeans IDE. We briefly introduce the tool and present an experiment that we have conducted with a group of students at our university. The results of the experiment indicate that projections have positive effect on program comprehension

Integrated documentation for software modules

Ein umfangreiches und komplexes Software-System muss in mehrere Module unterteilt werden, damit dieses verständlich bleibt. Dabei hilft eine Moduldokumentation, welche die Details eines einzelnen Moduls beschreibt. Existierende Werkzeuge zur integrierten Software-Dokumentation unterstützen die Dokumentation auf Modulebene nur unzureichend. So wird oftmals keine Integration in gängige Entwicklungsumgebungen geboten oder die Dokumentation eines Moduls wird zusammen mit der Dokumentation von Klassen und Methoden vermischt. Ziel dieser Diplomarbeit war es daher J-PaD, ein Werkzeug zur integrierten Dokumentation von Software-Modulen, zu entwickeln. Es erlaubt eine Dokumentation von Java-Paketen über eine flexibel anpassbare, grafische Oberfläche. J-PaD wurde als Plugin für die Entwicklungsumgebung Eclipse konzipiert, wodurch Entwickler dieses Werkzeug in einer gewohnten Umgebung verwenden können. Die Dokumentation eines Moduls wird dabei in einer separaten Datei gespeichert, welche sich jedoch in direkter Nähe zum Code befindet

Documentação colaborativa de software através de anotações contextuais.

A documentação de software, apesar de nos dias de hoje ainda ser considerada secundária em relação a outros artefactos resultantes do processo de desenvolvimento, desempenha um papel fundamental no uso eficaz e na compreensão do software. O processo de desenvolvimento de software tem sofrido evolução ao longo dos tempos, sendo hoje em dia geralmente uma atividade cada vez mais social, nomeadamente quando se olha para frameworks populares na web. Contudo, os mesmos princípios são aplicáveis a equipas mais pequenas e ágeis. Neste contexto, uma documentação minimalista, onde apenas se cria o conteúdo mínimo necessário e que vai evoluindo de acordo com as necessidades dos utilizadores, tem vindo a ser prática cada vez mais utilizada. A interação e comunicação entre leitores e autores, com o intuito de debater que alterações se devem fazer à documentação, é fulcral para essa evolução.O principal objetivo desta dissertação é mostrar que essa comunicação pode ser melhorada, nomeadamente com o uso de anotações contextuais na documentação. Para o alcançar, foi desenvolvida uma wiki, que irá servir de plataforma para a documentação colaborativa de software.A essa wiki foi adicionada a possibilidade de adicionar comentários a uma página e anotações a secções específicas, criando um ambiente propício à discussão entre leitores e autores.Finalmente, de modo a comprovar que a ferramenta desenvolvida cumpre o seu objetivo de melhorar a comunicação entre os vários intervenientes, esta será testada numa pequena equipa de desenvolvimento de software.Software documentation, despite still being considered secondary in relation to other artifacts that result from the development process, is fundamental in order to use and understand software in an efficient way. The software development process has been evolving over time, and is now an increasingly social activity, namely compared to other popular frameworks on the web. However, the same principles can be applied to small agile development teams. In this context, minimalist documentation, where only the bare minimum content is created, which will evolve according to the specific needs of the users, has been rising in popularity. The interaction and communication between both readers and authors, with the goal of debating what changes must be made to the documentation, is key to this evolution.The main goal of this work is to demonstrate that this communication can be the subject of improvement, namely with the use of contextual annotations in the documentation. In order to achieve this goal, a wiki has been developed, which will serve as platform for collaborative software documentation. Then, the possibility to add comments to a certain page and annotations to specific portions of that page was added to the wiki, thus creating a friendly environment to discussion between readers and authors.Finally, in order to verify that the developed tool fulfills its goal of improving communication and interaction between the various interveners, it will be tested in a small software development team