Now that we see an explosion in the number of software projects being launched every day, it’s more important than ever to clarify who did what on the project. At all levels (coding, testing, user validation…). And not only clarifying whether the author was a human or a machine but going deeper on their proifles to understand how much we can trust the software satisfies the needs of the users that is trying to help. For example, a period tracker app designed for women may inspire greater user confidence if the developers and testers include women sharing similar experiences and needs.
Reporting on diversity in software projects can enhance user trust and assist regulators in evaluating adoption. Recent AI directives include clauses that mandate diversity information during development, highlighting the growing interest of public regulators. However, current documentation often neglects diversity in favor of technical features, partly due to a lack of tools for its description and annotation.
As a potential solution, we introduce the Software Diversity Card, a structured approach to document and share diversity-related aspects within software projects. It aims to profile the various teams involved in software development and governance, including user groups in testing and software adaptations for diverse social groups.
Next sections describe in more detail our proposal for the software diversity card and how you can create your own with the tooling we provide. You can read the full details in our paper, published in the Information and Software Technology Journal.
Current reporting practices in OSS development
We studied the 200 top-starred repositories in GitHub for the top 5 programming languages. Information about the development team and non-coding contributors has been found in less than a third of the analyzed projects. Evidence of references on user testing activities are the lowest ones, averaging
3.5% across projects.
Table 1. Presence of diversity documentation in 1000 OSS projects.
| Area | C# | Java | JS | Python | TS | Avg |
|---|---|---|---|---|---|---|
| A1 – Refer to development team | 28.0% | 31.5% | 28.0% | 27.5% | 33.0% | 29.6% |
| …and mention profile aspects | 22.0% | 20.5% | 22.0% | 21.5% | 26.0% | 22.4% |
| A2 – Describe non-coding contributors | 30.5% | 27.0% | 32.0% | 27.5% | 31.5% | 29.7% |
| …and explain non-coding roles | 24.0% | 20.5% | 26.0% | 18.5% | 24.4% | 22.7% |
| A3 – Tests with Users | 3.5% | 3.5% | 1.5% | 5.0% | 4.0% | 3.5% |
| …and mention labor force | 0.0% | 0.5% | 0.0% | 0.5% | 0.5% | 0.3% |
| …and report platforms | 0.2% | 0.2% | 0.0% | 0.3% | 0.1% | 0.2% |
| A4 – Define specific use case | 84.0% | 74.5% | 78.5% | 83.0% | 68.0% | 77.6% |
| Specify target population | 34.0% | 28.5% | 32.0% | 36.5% | 30.0% | 32.2% |
| Describe specific adaptation | 15.0% | 13.5% | 17.0% | 21.5% | 15.5% | 16.5% |
| A5 – Define governance participants | 28.5% | 31.5% | 27.0% | 27.0% | 30.0% | 28.8% |
| Indicate funders | 27.0% | 15.0% | 32.0% | 19.5% | 30.0% | 24.7% |
What does the diversity card cover?
The card is organized into three main parts:
1. Participants
Not just the development team. We include:
- Development team profiles (demographics, locations, expertise)
- Non-coding contributors (translators, documenters, issue reporters)
- Testers and public reporters (including crowd-testing participants)
2. Usage Context
Who is the software for, and how does it adapt to different users?
- Target communities and their specific needs
- Software adaptations (accessibility features, language localizations)
- Social and cultural context of intended use
3. Governance
Who makes decisions, and who funds the project?
- Governance bodies and decision-making processes
- Funding sources (public, private, community)
- Project type (open source, corporate, research)
A language to formally specify diversity cards
To promote its adoption and ensure consistent use, we need to provide structured resources and integrate them with existing process management tools in software development initiatives.
For this reason, we have introduced a domain-specific language (DSL) designed for documenting software diversity. The DSL concepts are formalized using a metamodel but we also propose a textual notation, defined as a grammar, to create textual card descriptions that can be easily added to the repositories.
See an excerpt of the grammar
Start Creating Your Card Today
Our approach has been implemented as a set of open source tools available to everybody.
Our grammar is available as a Visaul Studio Code extension implemented in Langium. The Visual Studio Code extension provides capabilities for exporting software diversity cards to JSON and Markdown (MD) formats.
But to make it even easier to create diversity cards, we also offer a form-based input definition method, where cards are created by simply filling a web form.
One of the main advantages of this form-based tool is that it guides the user about each of the fields available and their expected format. For instance, as we can see in the figure, in the governance part, the user can create as many bodies as they need, assign the type of body using an option selector, and define, if needed, basic demographic information for each body. Another advantage of this web-based tool, compared to the presented language plugin, is the smooth installation step, as this can be accessed directly from the web browser, which is ideally for non-coding users.
Parting thoughts
We validated the card through two real-world case studies, analyzing public documentation and conducting interviews with development teams. The findings illustrate both the benefits and challenges of using the card in practice. Among the benefits, the card enabled the collection of valuable information not publicly documented, such as internal usability test results, which could enhance project transparency and value. The challenges included issues related to anonymity and sensitivity, which limited the collection of nuanced participant data, the dynamic nature of development teams, which complicates capturing their full composition and evolution, and adoption barriers, particularly the additional effort required for small- and medium-sized projects.
These results highlight the potential of the Software Diversity Card as a tool for promoting awareness and reporting of diversity, while also indicating areas for further refinement and support to ensure practical applicability across diverse software projects.