Bachelor's/Master's Thesis: Documentation and Architecture Support for Research Software

Research Software Engineering (RSE) plays a crucial role in modern scientific research, particularly in highly technical domains. However, research software is often developed under conditions that differ substantially from industrial software development. Projects may start as small scripts or prototypes, be planned as short-lived or disposable software, and later evolve into larger and more widely used systems. As these systems grow, the requirements regarding quality, maintainability, understandability, documentation, and architecture become increasingly important.

At the same time, documentation and architecture planning are often underrepresented in research software projects. Source code changes frequently, researchers developing the software usually have limited time, and software engineering activities compete with scientific priorities. In addition, researchers often come from domain-specific backgrounds and may have little experience with architecture modeling, for example using class diagrams. As a result, long-term usability and maintainability of research software can suffer, even if the software is scientifically valuable.

This thesis addresses this challenge by further developing, integrating, deploying, and evaluating two existing systems for supporting documentation and architecture understanding in research software projects. The first system derives documentation for source code using Large Language Model (LLM) calls and takes into account the terminology of the respective scientific domain. The second system deterministically derives class diagrams from Python and Java source code. The goal of this thesis is to combine these systems into a practical tool-supported workflow for research software documentation and architecture understanding.

For example, exported documentation could be extended such that a class diagram is shown together with adjacent classes for a documented class or module. This would help researchers understand not only the local source code but also its architectural context.

This thesis is related to the thesis topic Implementing Recommendations for Research Software Development. Selective collaboration between the theses is likely and will be coordinated by the thesis supervisor.

Previous Work

As part of previous work, two complementary systems have been developed to support documentation and architecture understanding in research software projects.

The first system uses LLM-based approaches to generate or support source code documentation. A key aspect of this system is that it considers terminology from the respective application domain. This is particularly relevant in research software, where code, concepts, and documentation are often closely connected to scientific terminology, models, experiments, or domain-specific workflows.

The second system deterministically extracts class diagrams from Python and Java source code. Such diagrams can support architecture understanding by making classes, relationships, and dependencies more explicit. This is especially useful in research contexts where developers may not have extensive experience with manual architecture modeling or UML-based documentation.

Together, these systems provide a strong foundation for improving documentation and architecture support in research software. However, they still need to be further developed, integrated into a coherent workflow, deployed in realistic settings, and evaluated with respect to usefulness, usability, correctness, and practical impact.

Topic and Approach

The goal of this thesis is to improve the long-term understandability, maintainability, and usability of research software by integrating automated documentation support with architecture visualization.

The thesis will focus on the further development and integration of the two existing systems. A central objective is to make the generated documentation more useful for researchers by combining textual explanations with architectural context. For example, when documentation for a class is exported, the documentation could also include a class diagram showing the class itself and adjacent classes, such as related base classes, subclasses, dependencies, or associated classes.

The exact technical focus can be adapted depending on whether the thesis is conducted as a Bachelor’s or Master’s thesis and according to the interests of the student.

The thesis will comprise the following main tasks:

Familiarization with the RSE context and previous systems
Review the Research Software Engineering context, the existing LLM-based documentation system, and the deterministic class diagram extraction system for Python and Java.
Analysis of documentation and architecture needs in research software
Identify relevant documentation and architecture understanding challenges in research software projects. This may include reviewing related work, existing documentation practices, and concrete needs of researchers.
Requirements analysis for system integration
Analyze how the two existing systems can be integrated into a coherent workflow. Relevant questions include:
- Which information should be exchanged between the systems?
- How should diagrams be linked to generated documentation?
- Which export formats are required?
- How can the workflow remain lightweight enough for researchers with limited time?
Design of an integrated architecture
Design a suitable architecture for the integrated system. The design should consider extensibility, maintainability, robustness, and practical deployability in research software projects.
Integration of documentation and class diagrams
Implement the integration between generated documentation and extracted class diagrams. For example, exported documentation may include diagrams that show the documented class together with adjacent classes and relevant relationships.
Deployment in a realistic research software context
Prepare the integrated system for practical use. This may include packaging, configuration, documentation, examples, CI integration, or deployment in one or more existing research software projects.
Evaluation of usefulness and quality
Evaluate the integrated system with respect to selected criteria such as:
- usefulness for understanding research software,
- quality and correctness of generated documentation,
- correctness and readability of class diagrams,
- usability of the workflow,
- effort required for adoption,
- perceived value for researchers.
The evaluation may include case studies, artifact analysis, comparison with existing documentation, structured feedback from researchers, or small user studies.
Reflection and derivation of lessons learned
Reflect on the benefits, limitations, and transferability of automated documentation and architecture support in RSE contexts. Particular attention should be paid to the tension between frequently changing source code, limited researcher time, and increasing quality requirements as projects grow.
Documentation and presentation of results
Document the system design, implementation, deployment process, evaluation results, and lessons learned in the thesis and present the results.

Depending on the scope, the topic can be adapted for either a Bachelor’s or Master’s thesis.

Possible Research Questions

Depending on the final thesis scope, the work may address questions such as:

How can LLM-generated source code documentation and deterministic architecture extraction be integrated in a lightweight workflow for research software?
How can class diagrams be selected and presented so that they support understanding without overwhelming researchers?
To what extent does the combination of textual documentation and architecture visualization improve the understandability of research software?
How can domain terminology be incorporated into generated documentation in a way that is useful for researchers?
What are practical barriers to adopting automated documentation and architecture support in research software projects?
How can automated documentation remain useful when source code changes frequently?

Our Offer

Two existing prototype systems as a strong technical starting point
A relevant and practice-oriented thesis topic in the area of Research Software Engineering
The opportunity to work on the integration of LLM-based documentation generation and deterministic architecture extraction
A topic with direct relevance for the sustainability, maintainability, and understandability of research software
Flexibility to shape the thesis according to your interests, for example toward implementation, tool integration, visualization, deployment, or evaluation
Access to realistic research software contexts and examples
Clear supervision and methodological guidance
Weekly meetings, either in person or remotely
Coordinated collaboration with related thesis projects at selected points
Insight into real-world research software development in cutting-edge scientific domains

Your Profile

You are pursuing a Bachelor’s or Master’s degree in Computer Science, Software Systems Engineering, or a related field
You are interested in Research Software Engineering, software documentation, software architecture, and maintainability
You enjoy practical software engineering work and want to create tools that support real users
You have programming experience, ideally in Python and/or Java
You are interested in documentation generation, static code analysis, architecture visualization, or LLM-based software engineering tools
You are able to work independently and structure an open-ended technical topic
You are willing to understand the needs of researchers and adapt tooling to practical constraints
You are interested in evaluating software engineering tools in realistic contexts
Experience with UML, class diagrams, static analysis, documentation generators, or LLM APIs is helpful but not strictly required
You are available for onboarding sessions at the beginning of the thesis

Contact

For more information, please send a short description of your background and an overview of your grades to Marc Schmidt at schmidt@se-rwth.de.