Be aware of different backgrounds Xperts may bring into a team; configure training so that less-familiar best practices can be acquired as needed. Members of  Xpert groups may come from domain sciences, from computer science backgrounds, or from environments where they learned to assist CDI  science teams through training on the job. For example, working with Unix commands, parallel programming models, and version control may be second nature to members with computer science backgrounds, whereas these very skills may be critical best practices to acquire by Xperts with the domain-science background. Vice versa, Xperts who have a domain degree are often well aware of the terminology gap, which facilitates communication with new science collaborators. Training for Xperts should accommodate these differences, allowing the trainees to focus on best practices they are not familiar with.

Prepare for skills needed beyond your current expertise, by networking with other Xperts. Modern CDI applications draw from a broad range of technologies, such as computing paradigms, programming languages, architectures, and algorithms. What’s more, this range keeps evolving. For example, a new application may demand expertise in machine learning techniques. Individual Xperts and those in small teams, serving a large CDI research community, will unlikely cover the needed skills. Besides, they may need to perform tasks across the entire software life cycle and be involved in project management. It is important to be able to recognize such situations and seek external advice. Maintaining contacts with other Xpert teams, who may be consulted when needed, is highly advisable.

Carefully identify and resolve terminology gaps. Keep vocabulary to the essentials. Explain using many examples. The gap between computer-science and domain-science lingo is an often mentioned issue in Xpert Network discussions. The challenge can be big if the same term is used by both collaborators, but with different meanings. Participants reported significant confusion and even incorrect project executions due to this challenge. Awareness of the issue and patience in trying to understand the collaborators’ viewpoints is critical. It was pointed out that the gap is wider than in a general software engineering context when trying to understand a customer, as science terminology tends to use rich vocabularies. Keeping the vocabulary to the essentials and investing time to explain new terms is key to successful collaboration. Using many examples and frequent feedback from both sides will help bridge this gap.

Devote substantial time to understanding the domain problem, turning possibly vague ideas into a feasible solution approach, and developing a project plan.  Many Xpert Network participants highlighted the importance of the first contact with the supported domain scientists and the approach taken to understand problems and develop solutions. In addition to awareness of the terminology gap, the relevance of investing time in understanding the goals and the functional as well as non-functional requirements was emphasized. Showing patience in the process is critical. The domain researcher needs to be helped to transform an initially often vague idea into a concrete plan. Developing specific requirements for the computational application and the underlying system is essential. Devote sufficient time. One challenge for the Xpert is to introduce the researcher to the possibilities of the to-be-created or improved software implementation and the underlying system while introducing only a small number of new terms. Recommendations include the use of many concrete examples and an inverted pyramid approach. The latter describes a possible solution in initially very few, high-level terms, which are then successively refined in discussions.

The situation is again related to that of software engineers with their customers, two important differences being:

1. the potentially large terminology gap mentioned above, and
2. the collaborative assistance situation, which often enables the inverted pyramid approach: As Xpert and domain researcher work side by side, refinements of high-level ideas can more easily happen over time, permitting the collaborators to invest their initial effort in defining the tip of the pyramid.

Make use of source code management and version control systems to track your software’s evolution. An Xpert with a software engineering background is well aware of the importance of software version control. At the same time, this importance needs to be advertised to domain experts, as pointed out strongly by the Xpert network participants.

Many successful science software applications had their origin in a  “toy program” written by a graduate student. It got gradually expanded by several authors, caught the attention of a wide audience, and ended up becoming an important research tool. Without version tracking, the history (origin, authors, relationship of features, and specific extensions) may no longer be known, making it difficult to extend further and obtain needed documentation. Learning version control methods and tools will not only help overcome these difficulties; it will also increase the productivity of the software developer as soon as the application exceeds the boundaries of a small program. What’s more, source code management tools greatly facilitate collaborative software development, enable software roll-back to a previous, well-defined state, and help developers start a new branch of the software. The latter can be important if, say, two graduate students want to add their own, separate feature sets. 

Xpert and domain scientists should review each other’s software written. Code review — a second person reading newly written software — is one of the best ways to catch errors and also to improve the code. Despite its effectiveness, it is often ignored, unless strictly mandated, and hence warrants mentioning here. A number of additional reasons make this practice particularly useful for an Xpert-domain scientist relationship:

• The two collaborators have different backgrounds, increasing the chance of detecting an issue that eluded the other.
• The review is effective in verifying that requirement and implementation match.
• It is a good way of transferring the knowledge of what the Xpert did to the domain scientist, who will continue the work after the collaboration completes.
• The discussions happening during code review provide excellent material for documenting the code and project.

Document your project to ensure long-term success, reproducibility, and obtain proper credit for your work. Software engineering teachings cover extensively the fact that well-documented programs are essential for software maintenance and extensibility. Yet, academic software is notorious for the lack of documentation, as pointed out forcefully by  Xpert Network participants. While raising awareness of the benefits is important, one also has to understand that academic processes and reward systems often do not support spending time on documentation. Most academic research funding pays for showing principles and developing prototypes, not production-ready software. What’s more, students are under pressure to graduate, whereby the functionality of the created software is more important than its documentation. If the software becomes successful, the original author often is no longer involved and thus has little incentive to retrofit a proper description. It is often the difficult task of the next generation of students in a team to accomplish these tasks. It helps, however, to understand these relationships. If one can identify the original creator, they may be willing to help, especially when offering them proper credit or co-authorship on a forthcoming publication. Vice versa, properly documenting the original authorship will ensure that such credit can be given. The reproducibility of scientific research is a concern that is currently gaining attention. Proper software documentation can be key to reproducibility.

Enable reproducibility and transparency by capturing data and software underlying scientific processes, using available software platforms. While the reproducibility of research results is a key requirement in any domain of science, there is a recent, increased focus on this issue in computation-based research. Reproducibility was highlighted as a significant concern in our Xpert Network discussions as well, pointing out that adding supporting software and data to a publication can increase the value significantly. This is of particular importance in large computational studies, where data analysis may play a central role in reaching conclusions. Disclosing the data and software underlying the research methods will add transparency.

Making use of software platforms, such as GitHub, GitLab, and container environments, such as Docker, can dramatically reduce the cost of capturing and describing the computing environment used to produce the scientific results.