Top tips

By Alex Nenadic, Alan Williams, Robert Haines and Alasdair Gray of MyGrid, Anton Güntsch of the Freie Universität Berlin, and Aleksandra Pawlik of the Software Sustainability Institute.

You have a piece of data-processing code, it works well, and both your colleagues and other researchers think it is useful. So, you decide to turn it into a Web Service so that it can be used by anyone with Web access. Yet do you know how to go about it? These Top Tips will help you get started.

Do not “press a button” on existing code

Creating a Web Service should not be a box-ticking exercise. It is very easy to think that providing a service can be done by running a tool over existing code. Web Services are nearly always implemented as an afterthought. As a rule, service providers usually have some local code and an interface that they set aside as a public service. Sadly, the interface often ends up being cumbersome…

Continue Reading

Tantalus Road through Hawaiian jungle - wiki is a Hawaiian wordBy Mike Jackson, Software Architect.

My EPCC colleague, George Beckett, recently e-mailed me to comment that "I'm conscious that wikis typically deteriorate into a mess of conflicting/out-dated materials, if not managed closely". George asked whether the Institute had advice on good practices for using a wiki. So, for George and others with wiki worries, here are our top tips on using a wiki for a software project...

1. Start as you mean to go on

Create some order at the outset and draw up an outline of the key areas of the wiki (e.g. Project Management, Dissemination, Design, Development etc.) and what they will contain, then create these areas on the wiki.

2. Appoint an editor

Your editor will "own" the wiki, manage its structure and regularly review, police, and tidy the wiki. The editor can help to ensure that your wiki remains structured and that your users respect the following tips...

3. Don't accidently create WikiWords

Wikis treat words in CamelCase (e.g. GitHub, SciPy) as WikiWords and create links to new child pages for these words, which appear as "WikiWord?" until a child page is created. These can make your text more difficult to read. Wikis provide annotations to tell the…

Continue Reading

Scott Henwood, Director of Research Software at the Canadian funder CANARIE gives his tips on building better software.

"I joined CANARIE’s Research Software program more than three years ago after a long career in commercial/industrial software development. The experience so far has been eye-opening. At the implementation level, software development in an academic environment is pretty much the same as software development in a corporate environment. The environments that corporate and academic software developers work in, however, are very different.

As corporations focus on profitability, they continually look for ways to make software development extremely efficient. Despite the differences in environment and goals, my observation is that there are some commercial development techniques that can be easily adopted by academic software developers. There are no doubt lessons that corporate software developers can learn from the academic community as well, but I’ll leave those for someone whose career has gone in the opposite direction of mine to explore. This post focuses specifically on research software – software that is designed to support scientific research in an academic environment."

Read the full article on the CANARIE website.

By Stephen Eglen, Software Sustainability Institute Fellow and senior lecturer University of Cambridge.

Late last year, I ran a workshop with the International Neuroinformatics Coordinating Facility (INCF) in Cambridge. It was regarded by all attendees as a success and it was suggested that we archive some tips for organising a small workshop. Here are those tips.

1. Get help with admin

We were incredibly lucky in that all the administration for the event was taken care of by the INCF, and in particular its program officer, Mathew Abrams. Everyone's travel plans were coordinated, and everyone stayed at the same (beautiful) college. Good admin is a fundamental part of a successful event, but it takes a lot of time to do well, so take any help you can get to ensure that your admin is done well.

2. Assemble a diverse audience

Rather than have the same people talking to each other, make sure there is plenty of new blood with people offering different perspectives. Although most attendees were neuroscientists at my workshop, an archeologist provided insightful advice and comments from his discipline. We also had a representative from the Wellcome Trust, and two editors (from Nature and PLOS).

3. Let everyone say their piece

Day one of the workshop was devoted to introductions. Everyone was invited to present a 15-20 minute talk, with plenty of time for discussion. Workshop run more smoothly, and collaborations are set up more efficiently, when…

Continue Reading

By Neil Chue Hong, Director.
Comic number 1869 from PhD Comics. (c) Jorge Cham. Used with permission.

The Software Sustainability Institute is proud to be associated with a major new paper on irreproducible research. The new paper is called "Top Tips to Make Your Research Irreproducible" by Neil Chue Hong, Tom Crick, Ian Gent and Lars Kotthoff, and is due to be published today (1 April) on arXiv. We present some excerpts of the paper with permission of the authors. Readers are encouraged to read the full version.

We have noticed (and contributed to) a number of manifestos, guides and top tips on how to make research reproducible; however, we have seen very little published on how to make research irreproducible.

It is an unfortunate convention of science that research should pretend to be reproducible; our top tips will help you salve the conscience of reviewers still bound by this fussy…

Continue Reading

You've created your software, it works and the response so far has been great. But now you want to make it available to a larger audience. How do you go about it?

You'll need to know how to package what you're trying to distribute. There is no point sharing your work if it is inaccessible to a new user, after all. Mike Jackson's blog post shows how to do this by making the package accessible and never forgetting that your users might not be as expert as you. You might also want to work with a technical writer to help create the best documentation.​

Obviously you'll need to know how to release it. Steve Crouch's Top Tips on this subject will show you how to do this, and just as importantly, when and with what licence. It's also good to think about whether people will be able to properly cite and describe your software.

You will also need to know how to…

Continue Reading

By Simon Hettrick, Deputy Director.

Have you ever needed to answer a big question that's fuzzily defined and can only hope of being answered by combining the experiences and knowledge of a wide group of disparate experts?

Whenever this situation occurs at the Institute, we apply the perfect solution: an unconference (like our Collaborations Workshop). Rather than sitting through a dull series of presentations, the attendees at an unconference are in control of what they do and how the conference works. This makes the confernece adaptive, so that the shifting boundaries of fuzzily defined questions can be honed and narrowed down until a solution is found.

At a good unconference you could have around 100 people all firing suggestions at you across a huge range of topics and, somehow, you have to accommodate these ideas on-the-fly into a constantly evolving agenda. Fortunately, the organisation of an unconference can be made much easier if you prepare in advance and follow our top tips.

1. Bag a good venue

People tend to remember two things about a venue: the food and the wifi. An unconference adds an extra requirement: good rooms.

You need a lecture theatre or another room of sufficient size to hold all the…

Continue Reading

By Mike Jackson, Software Architect.

You have been developing software that is becoming more popular. But now you are struggling to balance the need to develop and support your software, against the need to do your research. How do you convince funders to give you money to recruit a software developer to keep your users happy?

Here are our top tips in the form of four sets of questions that, by answering, will help you to convince funders.

1. What is the nature, and origins, of your software? What are funders helping to keep alive?

Provide an overview of your software including what it is designed to do, its capabilities and its novel features. Describe your target audience, but also mention other audiences the software might appeal to.

Describe whether it is an application, a library, a middleware or a service and how it is distributed (for example, in source or binary form, its licensing, a free or subscription service, etc.)

Summarise the provenance of your software, how it originated and when; which individuals, projects and organisations have been involved in its development; and who has funded development to date. Include an estimate of the person-hours (funded and unfunded) invested to date in developing the software…

Continue Reading

By Matt Turk, Columbia University.

I love Mercurial. It's easily my favorite version control system, and I use it for all of my projects. Much like git, bazaar, darcs and so on, it's a distributed version control system - it's decentralised, in that every clone of the repository has a fully-fledged set of history - and it enables you to create local changes, review past changes, and create experimental branches that are later abandoned.

Mercurial, first created by Matt Mackall in 2005, is written in Python, and developed by a community of users and developers spread all over the world. There are a few hosted mercurial offerings. Most notable among these is BitBucket, but it is also supported by SourceForge, RhodeCode, and Savannah. Mercurial is designed around the concept of a Directed Acyclic Graph (DAG) - basically, a line of development and changes that proceeds back to the initial source, only going in one direction. All the forks, branches, everything that happens in a source repository becomes part of this DAG (more on that later). Mercurial is released on a regular schedule - and there's little to no danger upgrading, because of rigorous backwards compatibility standards enforced in the code base.

If you want to get started using Mercurial, just type hg init. That creates a repository, and you can do hg add, hg commit, hg pull and hg push all you like. There's an introductory tutorial at Hg Init,…

Continue Reading

By Neil Chue Hong, Simon HettrickAleksandra Pawlik and Giacomo Peru.

The ability to communicate your work is vital, whether you are a researcher, software developer or manager. Lightning talks are a popular way of allowing many people to talk about their work in a short time, and making it easy to work out who you should grab for a conversation at the coffee break. (They're popular at workshops, like our Collaborations Workshop.). For many, the idea of giving a talk under such strict timing can be terrifying. These top tips will help you become an electrifying lightning talk presenter.

1. Finish on time

This applies to all presentations, but is especially important for a lightning talk! If you don’t finish on time, the audience will have missed a part - a potentially fundamental part - of your talk. Rehearse your timings a number of times (you can even do this in front of a mirror or a friendly audience). Learn your style - most people speed up when presenting in front of an audience, but some slow down or elaborate more. Write a script if it helps to time the talk, but don't read from the script when you present for real.

It's a good…

Continue Reading
Subscribe to Top tips