How documentation can improve your tools

Bioinformatics tools documentation and guidelines can come in handy when using a complicated piece of software. Yet, tools developers most often overlook the benefit of releasing documentation with their creations.

The main goal of tool documentation is to provide the basics of the software’s functionalities and guidelines on how to use it. Having such documentation will ensure great coverage and impact of your tool, as well as save you countless hours answering basic questions.

Different types of research software documentation

Software documentation can take various formats:

  • Manuscript, usually the original publication describing the tool.
  • Readme, which contains basic instructions for installation and use of the software.
  • Quickstart, a step-by-step protocol for installation and use of the software.
  • Reference manual, a comprehensive documentation of every configurable setting of the software.
  • FAQ, answers to most asked or anticipated questions.

Documentation-generating tools

Writing a comprehensive and easy-to-understand guideline can be a difficult task. For this, software have been developed to generate documentation directly from source codes. Here are some useful software that might help you create your documentation:

  • Doxygen: Generates documentation from source code. Supports most coding langages, including C++, C, Objective-C, C#, PHP, Java, Python, IDL and more. Doxygen can generate online documentation in HTML, or offline reference manuals in various formats. It can also extract code structure from undocumented source files.
  • Javadoc: Generates HTMP pages of application programming interfaces (APIs) documentation from Java source files.
  • Sphinx: Originally created for the Python documentation, this tool uses reStructuredText as its markup language and proposes various output formats (HTML, Latex, ePub, etc.), extensive cross-references, hierarchical structure, automatic indices, code handling, and more.
Figure-documentation-omictools
Example of documentation generated with Sphinx.

To learn more on software documentation and general recommendations, read this useful paper by Karimzadeh and Hoffman: Top considerations for creating bioinformatics software documentation.

No excuses not to write documentation next time!

Leave a Reply

Your email address will not be published. Required fields are marked *