Scientific Data Analysis: User Documentation 101

TL;DR: When publishing open-source tools for bio-image analysis special emphasis should be put on user-documentation. Users and developers have a different background and a language barrier limits knowledge exchange on how to use tools correctly. Writing a good user guide is a huge opportunity and worth the effort: Users get the most out of their data and developers can collaborate with them to build their scientific track record by showing applications of their tools to biological questions. This blog post outlines some of the most important aspects for writing good user documentation.

The Importance of Documentation

Good documentation cannot be underestimated. The best bio-image analysis software on earth is useless if nobody knows how to use it. In the 2020 BioImage Analysis Survey by Jamali et al (2021), Documentation is on place 2 in the context of what developers can do to improve their software. Only user-friendly Graphical User Interfaces (GUIs) seem more important.

Source: Added underline and cropped from Figure 7 in Jamali et al 2021, licensed CC-BY 4.0.

The Graphical Abstract

Sooner or later, potential users will find your data analysis tool on the internet, for example on github.com, imagej.net or the napari-hub. Most of them will not read your website in very detail if they can’t see on the first look what your tool does. Thus, add a screenshot or small figure at the very top of your page so that potential users can immediately guess what your software is good for. Spend some time in crafting this eye-catcher.

The Pitch

In most software repositories, such as GitHub and Napari Hub, you can enter a short sentence as description for your software. Use this opportunity to say what the tool does. Consider that the reader might not have the same knowledge as you do. They might come from a different field. “A Napari Plugin for Nuclei Segmentation” is a great description. A bad example is “A Napari Plugin for NOFLSEM” as Noflsem might not be well known to new users.

Quick User Guides

To make users getting started using your software, provide them a short list of things they need to do in order. For a Quick User Guide, you may not need to explain all parameters a user can enter in very detail. In Quick User Guides it’s more important to show users the entire workflow. If such a guide is much longer than one page, the users might think “That seems so complicated.” If you give them short text sections and screenshots (!) and they will give it a try. If screenshots contain a lot of elements, draw arrows and circles to point the users to the right places.

Video tutorials

Videos are worth a thousand words. You do not have to write a long story if you can provide a video tutorial. It may make sense to record videos of specific processing steps and have multiple of those on your tool’s website. Think of users who search for “How can I annotate data points?” and take a video for anwering only this question.

Alternatively, record an entire workflow while doing and also record your voice explaining what’s happening. Show some presentation slides in between to explain details. Upload the video on YouTube and you will see how many people are enjoying your explanation.

Target audience

Depending on your target audience, you may need to provide different user guides. If your tool is a Fiji plugin that is supposed to be used by clicking, videos may be the right documentation as explained above. If your Napari plugin can also be run from Python, provide example notebooks demonstrating how to do this.

Jupyter books are also an exciting way for documenting Tools that can be executed from Python. They enable to show short code-snippets followed by intermediate results the code leads to. It might be the best method for data science knowledge conservation and transfer these days.

Example data

When new users try your software for the very first time you should make sure that nothing can go wrong. Providing an example dataset is key for this. Provide data for which the tool is made. Hint new users that they should not try it in the first run with their own data, that might not be perfectly suited or needs careful parameter tuning. If the new users try the tool with provided example data, they will have a success feeling like “Wow, that was easy to use!”. This gives them motivation to invest more time to apply it to their own data and for parameter tuning if necessary. It shall be recommended to share example data via open access repositories such as Zenodo.org. There you can also see how many people were downloading and potentially reusing your data. Read this blog post to learn how to share data via Zenodo.

Installation instructions

When providing installation instructions, consider that your collaborators may not have the same technical expertise as you have. For some of us installing Python and Mamba/Conda packages is daily business. For some others it’s not. Give them a hand and explain in detail what needs to be done in order to run your software. Also link to other resources, such as this blog post to guide them in getting started with Python and Mamba. Keep in mind: precise installation instructions are key for reproducible data science.

Citation

We software developers in science don’t do all the work just for the fun. From time to time we also need to prove that the software we develop is useful to others. In the academic system, the most accepted way for doing this via scientific citations. Thus, make sure you give users a hint of how to cite your software. If there is no publication out yet you can link to, add a Digital Object Identifier (DOI) to your software and make your software citable. Read more about creating DOIs for GitHub repositories using Zenodo and citation files.

Usability testing

After you have written the user guide and installation instructions, give them to a colleague who has never used your software before. Let them try and observe what they are doing. If you see them struggling, consider updating instructions at that point. Observing users like this is called usability testing and it is a great tool to improve user experience.

Keep your documentation up-to-date

Software that doesn’t change over time is dead. Changes are welcome as they show that users are working with the software, new use-cases appear and someone is taking care of the software. But also documentation needs to be maintained. Whenever you update your software, also update the documentation. Make this good practice. Nothing is more annoying than a great tool that does what you need, but you can’t use it because the documentation is outdated.

Reusing this material

This blog post is open-access. Figures and text can be rused under the terms of the CC BY 4.0 license unless mentioned otherwise.

(7 votes, average: 1.00 out of 1)