Key Points

Introduction

  • Reproducibility: Well-documented software is easier for other researchers to understand and use with confidence, enabling them to reproduce your results, validate findings, and build 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 will be easier to maintain in the long term if others can learn about it and take it on after the original developers move on.
  • Sustainability: Readable, documented code is easier to maintain and reuse, extending the useful life of your software.

Documentation examples

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 succinctly.
  • 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 reports, 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 can be published to GitHub Pages using the mkdocs gh-deploy command.

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.