Template for software repositories by the Caltech Library

This is a template README file for software repositories. This first paragraph of the README should summarize your software in a concise fashion, preferably using no more than one or two sentences.

Table of contents

• Introduction
• Installation
• Quick start
• Usage
• Known issues and limitations
• Getting help
• Contributing
• License
• Acknowledgments

Introduction

This repository is a GitHub template repository for creating software project repositories at the Caltech Library. The associated wiki page explains how to use the template repository.

This README file is in Markdown format, and is meant to provide a template for README files as well an illustration of what the README file can be expected to look like. For a software project, this Introduction section – which you are presently reading – should summarize in general terms what the software does, the need(s) it addresses, the programming language(s) it's written in, and optionally, links to other resources that can help orient readers. Ideally, this section should be short and use plain language. Keep in mind that not all readers who happen upon your project will be familiar with the topic area.

Installation

Begin this section by mentioning prerequisites that may be important for users to have before they can use your software. Examples include required hardware, operating systems, and software frameworks.

Next, provide step-by-step instructions for installing your software, preferably with examples of commands that can be copy-pasted by readers into their computing environments. If your software can be installed using common installers or package managers (e.g., pip, npm, brew, apt, etc.), illustrate how it can be done using code blocks in the Markdown file so that it's clear to readers. For example,

sh pip install yoursoftware

For installation methods that don't involve command lines, try to provide screenshots along with written instructions to help readers figure out what they need to do.

Subsections may be appropriate within this Installation section for different operating systems or particularly complicated installations. Keep in mind, though, that the more complicated the installation process is, the more likely that users will encounter difficulties and give up.

Quick start

Nobody wants to read long explanations about how to use your software before they can try it, especially while they are still trying to decide whether to try it at all. A Quick start section right after the installation instructions helps readers figure out what's involved.

Explain the minimal configuration (if any) required to start using the software, then provide the simplest example or command that demonstrates actual functionality implemented by your software. If your software is command-line oriented, provide examples (again using code blocks in the Markdown file).

sh yoursoftware argument1 argument2

If your software is not command-line oriented, try to provide screenshots – preferably annotated with arrows or other guidance – to show readers how to use the software.

If possible, avoid animated GIFs or video tutorials, for the following reasons: users who turn off animations in their browsers may not even see them, videos hosted on other platforms may disappear over time, videos take more time to keep updated as your software changes, and (at least in this author's experience) a sizeable number of people dislike video tutorials and won't play them anyway.

Usage

This Usage section would explain more about how to run the software, what kind of behavior to expect, and so on.

Begin with the simplest possible example of how to use your software. Provide example command lines and/or screen images, as appropriate, to help readers understand how the software is expected to be used. Many readers are likely to look for command lines they can copy-paste directly from your explanations, so it's best to keep that in mind as you write examples.

Some projects need to communicate additional information to users and can benefit from additional sections in the README file. Use subsections as needed. It's difficult to give specific instructions – a lot depends on your software, your intended audience, etc. Use your judgment and ask for feedback from users or colleagues to help figure out what else is worth explaining.

Known issues and limitations

In this section, summarize any notable issues and/or limitations of your software. If none are known yet, this section can be omitted (and don't forget to remove the corresponding entry in the Table of Contents too); alternatively, you can leave this section in and write something along the lines of "none are known at this time".

Getting help

Inform readers of how they can contact you, or at least how they can report problems they may encounter. This may simply be a request to use the issue tracker on your repository, but many projects have associated chat or mailing lists, and this section is a good place to mention those.

Contributing

This section is optional. If your project accepts open-source contributions, this is where you can welcome contributions and explain to readers how they can go about it. It can be as simple as pointing people to a CONTRIBUTING.md file in your repository.

License

Software produced by the Caltech Library is Copyright © 2024 California Institute of Technology. This software is freely distributed under a modified BSD 3-clause license. Please see the LICENSE file for more information.

Acknowledgments

This final section is where you should acknowledge funding and/or institutional support, prior work that influenced or inspired your project, resources that you used (such as other people's software), important contributions from other people, and anything else that deserves mention. After all, nothing is truly done in isolation; everything is built on top of something, and we all owe debts to other projects and people who helped us, supported us, and influenced us.

This work was funded by the California Institute of Technology Library.