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

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

Addressing Sustainability in Portuguese Museums and Heritage: The Role of Cultural Policies

The Future Museums Project Group was created under the Portuguese Ministry of Culture with the mission of proposing recommendations for a 10-year public policy for museums, palaces, and monuments, considering sustainability, accessibility, and innovation issues and their relevance in society. Against this background, museums were understood as agents of change with a role to play in achieving a more sustainable future, and culture as a fundamental pillar for democracy and sustainable development. This study discusses the findings of the project, focusing on three features that highlight the approach adopted to sustainability, which included collections management, participation, and mediation. Drawn from empirical research, a series of concrete recommendations, both for policy makers and museums, are discussed. The study concludes by arguing that cultural policies must place sustainability at the core of their strategy in order to function as a framework to drive and implement sustainable development practices in museums and heritage. Furthermore, within the scope of post-pandemic recovery plans, climate emergency, and the energy crisis, it is even more pressing that cultural policies provide support for museums and heritage and ensure that they have the conditions and resources to be able to move forward in a more integrated manner, thus contributing to a sustainable future.UIDP/00057/2020, UIDB/00057/202

Ontology-based security modeling in ArchiMate

Enterprise Risk Management involves the process of identification, evaluation, treatment, and communication regarding risks throughout the enterprise. To support the tasks associated with this process, several frameworks and modeling languages have been proposed, such as the Risk and Security Overlay (RSO) of ArchiMate. An ontological investigation of this artifact would reveal its adequacy, capabilities, and limitations w.r.t. the domain of risk and security. Based on that, a language redesign can be proposed as a refinement. Such analysis and redesign have been executed for the risk elements of the RSO grounded in the Common Ontology of Value and Risk. The next step along this line of research is to address the following research problems: What would be the outcome of an ontological analysis of security-related elements of the RSO? That is, can we identify other semantic deficiencies in the RSO through an ontological analysis? Once such an analysis is provided, can we redesign the security elements of the RSO accordingly, in order to produce an improved artifact? Here, with the aid of the Reference Ontology for Security Engineering (ROSE) and the ontological theory of prevention behind it, we address the remaining gap by proceeding with an ontological analysis of the security-related constructs of the RSO. The outcome of this assessment is an ontology-based redesign of the ArchiMate language regarding security modeling. In a nutshell, we report the following contributions: (1) an ontological analysis of the RSO that identifies six limitations concerning security modeling; (2) because of the key role of the notion of prevention in security modeling, the introduction of the ontological theory of prevention in ArchiMate; (3) a well-founded redesign of security elements of ArchiMate; and (4) ontology-based security modeling patterns that are logical consequences of our proposal of redesign due to its underlying ontology of security. As a form of evaluation, we show that our proposal can describe risk treatment options, according to ISO 31000. Finally, besides presenting multiple examples, we proceed with a real-world illustrative application taken from the cybersecurity domain.</p