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!

OMICtools uses code versioning to enhance tool traceability

versioning-feature-omictools

Software tools on the Web evolve over time, with developers adding or removing features to improve their product, making code versioning an essential aspect of sustainable software development. Reliable code versioning allows developers to automatically track their work and revert to previous versions when needed.

Discover here how OMICtools can help you facilitate the traceability of your tool – and learn how to successfully upload your work in a community-controlled repository.

Benefits of version control

  • Provides a mechanism to keep track of code changes
  • Allows you to track the history of changes, work on the same code files, and merge code from different branches
  • Shows conflicts on code merges, allowing you to resolve them quickly

Following the FAIR data principles

The FAIR system provides recommendations for scientific data management and stewardship. OMICtools applies the FAIR guidelines to bioinformatics tools, by making them easily Findable, Accessible, Interoperable and Reusable.

  • Findability: Software and code versions are easy to find with the OMICtools advanced search engine. We continuously collect and update information from original articles, websites and repositories to make available the latest bioinformatics tools.
  • Accessibility: OMICtools ensures ongoing access to software tools, contributing to make knowledge and support available for users. Clear and accessible relevant information as well as a direct link to the original source are provided for each tool. We also provide metadata about the tool maintenance and use (name and email of the tool developer, forum and feedbacks from the biomedical community).
  • Interoperability: As far as possible, we record all tools which can be combined with other datasets by either users or computer systems. Maintainability of software is only one of the quality dimensions. Each tool on the OMICtools website also has a unique Research Resource Identifier (RRID), developed under the Resource Identification Initiative, which is transferred to the Neuroscience Information Framework (NIF) registry.
  • Reusability: OMICtools keeps a complete history of code versions so that they can be easily accessed and/or downloaded. This long-term software archive allows all users easy access to a previous version. 

Uploading and versioning your source code

If you want to version your source code, you can get started by finding your tool in the OMICtools repository using the search engine. Once you find it, click the upload version button and follow the instructions. All you need to do is indicate the version of the source code, the operating system and architecture, and add the publication  linked to the code. It’s as quick and easy as that – and of course you can contact us with any questions.

Once your code is uploaded, the programmatic access to DataCite’s API automatically generates the corresponding DOI. This unique identifier is defined by the International DOI Foundation and assigned by OMICtools to allow precision long-term preservation of your tool. If a DOI has already been attributed for your code version, you can let us know and it will be directly imported from the software platform you used. The DOI and files can’t be modified later.

omictools-versioning-and-DOI

This control repository service is designed to facilitate the development, maintenance and follow-up of bioinformatic tools by the designers themselves.

omictools-distribution
An overview of the variety of distribution channels of the tools

Remember that each published source code version is registered with a unique DOI which provides a permanent identification of your resource, even if material is moved or rearranged. Hence OMICtools, not only supports scientists in the analysis and understanding of biological datasets, but also improves the precision of citing bioinformatics methods used to produce and reproduce results, thereby promoting the quality of scientific publications in accordance with the FAIR guiding principles for scientific data management.

Want to share your thoughts? Offer your feedback. Tell us if you’re satisfied and what you think can be improved.

3 tips to boost your OMICtools profile page

profile-page-community-omictools

After four years on the road (OMICtools was launched in 2013), it was time to make some changes to our user profile – and a new front-end version has now been implemented! You can customize your profile page quickly and easily, with each section of the profile page re-worked and re-designed to streamline what you want the community to know about you. 

Now’s the time to increase your visibility, and we can help you to succeed

At OMICtools we strive to offer you a better way to identify the right tools for your biomedical data. Today, we are working to make OMICtools the number #1 biomedical community platform, which also allows you to network with your peers, and speed up your scientific career.

When you register with us, a profile page is created and any activity you are involved in on OMICtools will be automatically displayed, highlighting your skills and expertise to establish your scientific reputation. So for example, if your add badges to credit your tasks relating to your tool development project, they will be directly acknowledged in your profile. Likewise, when you bookmark tools and put them into collections, your favorites will automatically appear on your profile and can be seen by other users.

Regardless of the social media platform you’re working with, presence and a personal touch are two keys to success. That’s pretty straightforward to do on Github, ResearchGate or Mendeley – and now it’s also easy to do on OMICtools – an entirely bioinformatics platform.

In short, the more customized your profile page, the greater the extent of your reach. Here are 3 tips to help you to stand out from the crowd.  

1. Complete your professional summary

Your description is the first thing visitors will see. If you want to draw people’s attention to your profile, create a strong presence. Not only will you be more easily seen but other users you interact with will show up in your discussion streams, which will make networking easier for everyone.

We suggest you add a profile picture and your full job title after your username to give yourself a clear brand. We also recommend your professional summary includes a description of what you do and gives an indication of why you’re on OMICtools. Make it easy for the reader – keep it short and direct.

Check out the profile settings located on the menu on the left side of your page to add more content. We recommend that you include:

  • your current position and where it is
  • your work experience and qualifications
  • your social profiles
profile-omictools
A screenshot of an edited page

2. Share your work output

OMICtools is a great place to make your projects available openly. You can let your target audience know about your published work in the work experience section, along with a link to your article. Add your ORCID unique researcher identifier to distinguish yourself and your work from that of other researchers. If you don’t already have one, you can register for an ORCID and link it to your profile.

If you’ve participated in tool design, you can add a contributorship badge via the tool site and it will automatically appear in the bioinformatics projects section of your profile – if your tool isn’t already on OMICtools, submit it to the right category and then link it to your profile (and ask us if you need help submitting a tool!).

badges-omictools-community
The list of badges allowing you to credit your expertise for specific tasks in software development (conceptualization, data curation, administration, testing, etc.).

3. Be active

A strong social media presence in the bioinformatics community can serve as an important foundation for your professional success! In June 2016, Kudos and the Altmetrics Research Team at the Centre for HEalthy and Sustainable CitieS (CHESS), and the Wee Kim Wee School of Communication and Information at Nanyang Technological University (NTU, Singapore) analyzed user data and found that 51% of registered Kudos users were STEM researchers sharing their work, 29% were social sciences researchers and 8% were humanities researchers. This demonstrates the engagement of STEM researchers, and how they are leading the way in using innovative tools to disseminate their research (from Williams et al., 2017. The new alchemy: Online networking, data sharing and research activity distribution tools for scientists. F1000Research).

Being active on OMICtools is an easy way to reach your target audience. Open discussions in the tools’ forum to solve issues and be recognized as an expert in bioinformatics. Your comments will drive traffic to your profile and your tools.

Rating and reviewing tools is important. Leave relevant reviews on tools in your area of expertise. The bioinformatics audience is influenced by community feedback. The more reviews you post, the better your chances of ranking among the top contributors and appearing at the top of the experts list for your field.

skills-and-expertise-omictools

review-omictools-profile
An overview of the interactions you can see on a profile page

Thank you for your continuing support – we hope the new user profile release will contribute to making your experience on OMICtools easier and more effective, so check it out – just login and go to “Edit profile”!

Want to share your thoughts? Offer your feedback. Tell us if you’re satisfied and what you think can be improved.