Guides

Our guides can help you with all the different aspects of software sustainability. We can help you choose software development processes and techniques to protect your software and ensure it has a sustainable future.

Is there something you would like to know more about? We're always happy to provide our expertise on a new subject, so if there's something you would like to know more about, please contact us.

Community building

Starting a community - taking your software to the world - Whether for research, administration, learning or teaching, software is an increasingly valuable tool and output, and needs to be managed as such. Starting a community is, of course, an important step in software sustainability.

How to run a Software Carpentry boot camp - A boot camp is a workshop during which participants learn software skills based on shorts tutorials and hands-on practical exercises. This guide tells you everything you need to know about running your own boot camp.

Building a better community - Building a community around software is an important step for its sustainability. An active community can become self-supporting: answering queries raised by community members and contributing new functionality and bug fixes back to your project.

Recruiting champions for your project - Promoting your software is vital if you want to increase its use and generate interest in your research. Rather than singing the praises of your own software, it is often more persuasive to have a satisfied user spread the word for you.

Recruiting student developers - It's frustrating when you have an idea for improving your software, but lack the resources needed to realise it. Not all is lost! Your idea might be the perfect basis for a student project.

Data

Our thanks to the Digital Curation Centre (DCC) for providing links to these guides. The DCC is a world-leading centre of expertise in digital information curation with a focus on building capacity, capability and skills for research data management across the UK's higher education research community.

How to Develop a Data Management and Sharing Plan - Planning for the effective creation, management and sharing of your data enables you to get the most out of your work, bear in mind the wider context and consequences of different options, and helps make the research process easier.

How to License Research Data - This guide will help you decide how to apply a licence to your research data, and which licence would be most suitable. It should provide you with an awareness of why licensing data is important, the impact licences have on future research, and the potential pitfalls to avoid.

Licences

Choosing an open-source licence - There are so many useful resources on the web when it comes to open-source licensing that it can be confusing. This guide highlights the best resources that provide clear information about choosing a licence for software.

Open source

Supporting open-source software - You've written and released your open-source software, and now you've started receiving support queries. How do you support your software, handle questions and resolve bugs? Don't panic! This guide will help.

Choosing the right open-source software for your project - A lot of time is invested in setting up new software, and if you haven't done your homework, you could be making an expensive mistake. This guide takes you through the questions you should ask before you invest your time in new software.

Project management

Top tips for software developers working with researchers- 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.

Approaches to software sustainability - The way that you approach sustainability will be depend on many factors, such as the how important is the software, how mature is it, what is the size of its community and what resources available for achieving sustainability? This guide summarises the different approaches to achieving software sustainability.

Before starting a new software project - Whether for research, administration, learning or teaching, software is an increasingly valuable research tool and output, and needs to be managed as such.

Your project is ending. Don't panic! - To ensure valuable ideas and investment are not lost, decisions need to be made on what is to be done with the outputs from the development process. Just because you’ve finished with it now, doesn’t mean you or someone else won’t want to return to it at a later date.

Sustainability and preservation framework- A key challenge in digital preservation is being able to articulate, and ideally prove, the need for preservation. A clear framework of purposes and benefits facilitates making the case for preservation.

Congratulations: You've inherited some code! - This briefing paper is targeted at software developers and project managers who deal with taking over code that was developed by others, and where no proper handover has occurred.

Choosing project and product names - In this guide, we'll take a look at how to choose a good name and the common pitfalls. We'll also look at searching for already used names (including trademark searches). Finally, we'll discuss our understanding of registered trademarks and passing off - two laws that can affect name choice.

Publicising software

How to cite and describe software - It can sometimes be hard to understand, reproduce or reuse research done using software due to the way in which software is cited and described in papers. This guide provides recommendations as to how to cite and describe software when writing papers or reports.

Hosted continuous integration - A list of providers delivering hosted continuous integration to save you some of the time and effort in deploying a continuous integration server yourself.

Help! My developer is running away!- This paper provides guidance on how to perform a technical handover, which will ensure that the soon-to-leave developer will impart his or her valuable technical knowledge and identify traps and pitfalls you should avoid.

How to create and manage SourceForge projects - SourceForge is a free and well-established open-source project repository. It currently hosts over a quarter of a million open-source projects and is used by over 2.7 million developers. In this guide, we'll provide an overview of SourceForge and a how-to for common SourceForge tasks.

Best practice for using cloud in research- This guide for researchers will help you understand what cloud computing is, the benefits it may be able to offer you as a researcher and the different options available for gaining access to cloud computing resources. It will guide you in assessing whether to use a cloud and in planning the porting of your applications to your chosen cloud.

Best practice for funding the use of cloud in research- This guide for funders, senior managers and research directors will help you to assess requests for funding for cloud computing resources; assess requests to provision cloud infrastructures; and to provision shared cloud computing infrastructures to researchers across a range of institutions.

Software development: general best practice - You will find that development of new code and maintenance of existing code is easier if you adopt established principles and best practices. This guide shows you how to approach a new software development project.

Ready for release?- To get people using your software as quickly and painlessly as possible, you should invest a little of your time preparing everything your users will need before you release your software. This guide describes some simple things you can do to improve your users' experience of your software.

Defending your code against dependency problems- Rather than re-invent the wheel, it's a common (and good) practice to develop software that uses third-party software, but problems can occur when a new version of the code causes an incompatibility. In this guide, we describe how to choose software and develop code to avoid dependency problems.

Developing maintainable software - If you want to increase the uptake of your software, make it easy to extend (and fix) and make it maintainable. This guide provides advice on the design and development of maintainable software that will benefit both you and your users.

Writing readable source code- Although it ends up being processed by a machine, source code evolves within our hands. We need to ensure that we can understand what our code does and if it does this correctly, sometimes months after we wrote it. Our peers need to understand how our code works to have confidence in our research. Writing readable code costs only a fraction more time than writing unreadable code, but the payback is immense.

Testing your software - Software development doesn't end when the software is written. How can you, and any developers you work with, be sure that your software meets its requirements? Does your software work as expected, and will it continue to work over its lifetime?

Adopting automated testing - An example of how automated testing can be adopted for software to give researchers the security to refactor, extend, optimise or tidy, their code without the overhead of having to implement dozens of unit tests at the outset. This guide arose from our open call consultancy projects with QuBIc, TPLS and Distance.

Software evaluation guide- Assessing the quality of software - either your own or someone else's - is a tricky balance between hard objectivity and the very subjective (but very valid) individual user experience. The Institute provide a software evaluation service based on two complementary approaches developed over many years in the research software arena. This guide explains how we go about it!

Using Git with shared folders and virtual machines - Virtual machines running older operating systems might not be permitted to connect to a network, and this precludes the use of off-site source code repositories. This guide provides a workaround by which the use of shared folders, between a virtual machine and its network-aware host, and Git, with its support for both local and remote usage, allows for off-site source code repositories to be used with the virtual machine.

Generating Google maps out of Google spreadsheets - Say you've got a Google spreadsheet with a column for addresses. It could be street addresses or postcodes. You want to map this data and embed the map into a website. Maybe you also want the map to update dynamically as more rows are added to the spreadsheet. What are your options?