Introduction

  • Reproducibility: Well-documented software is easier for other researchers to understand and use with confidence. It enables them to reproduce your results to replicate research findings, enabling others to validate them and building trust in your research outputs.
  • Collaboration: Clear instructions enable other researchers to use and collaborate with your software and research projects.
  • Knowledge transfer: Your software package will be easier to maintain in the long term if others are able to learn about it and look after it after the original developers move on.

Writing README files

  • A README file serves as an introduction to your software, guiding users on installation, usage, and understanding its capabilities.
  • Consider the user’s technical background; write clearly and avoid jargon.
  • Markdown is a recommended format for creating headers, bold text, bullet points, etc.

Documentation strings

  • Docstrings are special comments that describe the purpose of a function and its inputs and outputs.
  • Structure your docstrings to convey more information, with a concise introduction.
  • Documentation strings allow you to break your documentation into bite-size chunks, with one overview comment per function.

Code readability

  • Try to inject as much meaning into your source code as possible by naming things clearly and succintly.
  • Use comments to explain your rationale—even if the code seems obvious to you know, think of the future benefits!
  • Label functions and variables with type hints to tell the user what data types are expected.

Contributor guidance

  • Encourage collaboration: There are many ways to contribute to a research software project, including bug reoprts, feature suggests, design discussions, documentation, and software engineering.
  • Clear processes: Explain the process for making changes and having them included into the code
  • Bug reports: Create simple ways for users to report issues and have these problems resolved in a timely manner.
  • Communication: Create appropriate communication channels so that design discussions and proposed changes may be worked through transparently.

Documentation sites

  • Structured documentation websites are very useful for users to learn to use all kinds of digital systems, ensuring its successful adoption by the wider research community.
  • Documentation sites contain comprehensive installation instructions, user guides, and troubleshooting tips.
  • There are several libraries that may be used to generate documentation sites.
  • Documentation websites may be deployed to a hosting platform.

Command line interfaces

  • Command line interfaces (CLIs) are terminal commands that provide an easy-to-use entry point to a software package.
  • Researchers can use CLIs to make their research code easier to use by providing well-documented options, hiding the complexity of the software.
  • Most programming languages offer frameworks for creating CLIs. In Python, we do this using the argparse library.