Posted by m.jackson on 1 October 2014 - 3:00pm 

By Mike Jackson, Software Architect

Working with researchers is something the Institute has been doing for many years now. So we thought it was about time to put together our top tips for software developers working with researchers to help foster productive, and enjoyable, collaborations.

1. Remember they are not software developers

You may know the difference between centralised and distributed revision control, classes and objects, pass-by-value and pass-by-reference, upcasting and downcasting, coupling and cohesion, processes and threads, or a stack overflow and StackOverflow, but your researcher may not. Knowing how to knock together a few dozen lines of code does not make someone a software developer, as writing code is just a fraction of what a software developer does.

Be aware of your researcher’s level of knowledge about software development and keep in mind that it can be hard for people to admit that they don’t know or don’t understand something.

It can also help to adopt a technique from storytelling—show, don’t tell. Don’t tell them to apply the factory pattern, a recommendation daunting in its abstract vagueness. Rather, provide an introduction to the factory pattern and show them an example of how the factory pattern would be implemented in their code. The recommendation then becomes both concrete and relevant, and the researcher has a head start on how to implement it.

2. Remind them you are not a researcher

If your researcher throws out a blizzard of terms like Navier-Stokes equations, reverse complement of a DNA sequence, 4D MRI scan, cooling muons, or phase angles, or anything else which leaves you baffled, then ask for an explanation or a diagram. Try to identify those aspects of their research it is necessary for you to understand and those that it is not. Always remember that the only dumb question is that which is not asked. On a related note...

3. Remember that you don't have to know as much about their research as they do

Otherwise you'd be them! You may find you need to understand less about what they do than you think you need to.

4. “How on earth do I secure my data using a protein kinase inhibitor?”

To you, PKI is public key infrastructure, to a medical researcher it is a protein kinase inhibitor. In certain programming languages, a slice is an array extracted from another array. In brain imaging, a slice is a 2D image of a cross-section of the brain. What may be a well-understood term in software development may also be a well-understood term to your researcher, but with a completely different meaning. And vice-versa. Be aware of the potential for confusion around such common phrases as dictionary, test, model,  grid or cloud (is that a computing cloud, point cloud, electron cloud, or, cloud-in-the-sky cloud?). Acronyms hold particular pitfalls: IDE either stands for infectious disease epidemiology or integrated development environment, while SLA can be a service-level agreement, a software licence agreement, a specific leaf area, or the Symbionese Liberation Army.

A little elaboration, and expanding acronyms on first use, may help you and your researcher understand each others’ phraseology. And, while we’re on speaking the researcher’s language…

5. Position benefits within the context of research

What benefits might most interest researchers? Modularity, maintainability, portability and extensibility? Or saving time, bringing in new members of a research group, surviving the departure of a researcher, promoting uptake of their research within their community and across communities or domains, or increasing their impact and contribution to reproducible research?

Explain how good software development practices could benefit their research. For example, maintainable software can help reduce the time to fix bugs and implement extensions which can in turn free up more time for research. Extensible software can be easier for others to extend, which can help encourage exploitation of the software by other researchers, which can also contribute to impact. Releasing well-documented code, and its tests, can furthermore contribute towards reproducible research.

You will find Best Practices for Scientific Computing a useful paper to understand how software development can contribute to research.

6. Put their needs before your interests

It can be tempting, especially in the presence of myriad new technologies, to pick the shiniest, bleeding edge tools or technologies out there because they look interesting and you’d like to play with them. This can be risky. Your brand new toy may quickly fade into obscurity as the hype fizzles out. A competing product may gain traction and leave the one you have chosen by the wayside, unsupported and undeveloped. A product may have rapidly evolving APIs which can incur a significant maintenance burden to keep up with latest releases. What might be a great tool or technology to you may be an installation, usability, and maintenance nightmare for your researcher and their colleagues.

Similar comments apply to your personal preferences. You may be a Linux disciple, but if Microsoft Windows or Apple Macs are the platforms of choice of your researcher and their community then swallow your distaste and any ideas about forcing Linux virtual machines onto them! Or, as our PIs Carole Goble and David De Roure have put it: "Fit in, don’t Force Change."

Your researcher is your customer and their requirements should be paramount. If that means using something dull, but tried-and-tested, proven and stable software, then so be it. What counts the most for scientists is "not clever software or innovative technologies but rather content and relevance."

7. Put their needs before their interests

Look out for your researcher, who may be prone to falling for the latest tech-hype craze or flash-in-the-pan too.

8. Don’t develop what you don’t need

It can often be tempting to implement features that might be useful in the future, even though neither your researcher, nor any user of their software, have requested this. You and your researcher should together resist this! Implementing features that might be useful takes time both from implementing features that definitely are useful, or are necessary, and from improving or fixing what you already have. You may end up with a lot of code that needs to be maintained, even though it is never used. As Don Wells put it: "Don’t Solve a Problem Before You Get to It" and adopt the extreme programming principle of YAGNI—You Aren’t Gonna Need It!

9. Focus on small shared successes leading to larger goals

Once having collected your researcher’s requirements, it is easy to go off and address these, returning with a complete solution, only to have them say "that’s not quite what I had in mind." Working on small, short duration tasks – adopting rapid prototyping or iterative development, releasing early and often—allows for you to get feedback more rapidly on whether, or not, you are addressing your researcher’s requirements, especially if the researcher’s requirements are rapidly evolving as a result of their research. Your researcher will appreciate your responsiveness. By sharing the achievements of these small stepping stones, you'll work better together as equals, which brings us to…

10. Develop software with your researcher, not for them

Encourage your developer to contribute to the design and development of the software. Help your researcher understand what changes you make to the software and why.  This can serve as knowledge transfer of software development to your researcher, helping them improve their skills and knowledge. It also helps improve the bus factor of the software itself. Fostering a sense of collective ownership and collaboration will reduce the chances of them coming to regard you as their dogsbody, and you viewing them as a meddlesome amateur who just mucks up your good work.

On that note, there you have it—our top tips for software developers working with researchers. Why don't you tell us what you think?