Chapter 7 Creating handy reference guides
7.1 The goal of a reference guide
Reference guides are the dictionary of your tool: they aren’t meant to be read front to back, but the best ones are easily searchable. Your user will have something in mind that they are trying to find information on – the quicker they can find it, the quicker their question can be answered.
Our goal for a reference guide is to be as comprehensive, navigable, and as always, as clear as possible.
7.2 Characteristics of handy reference guides
7.2.1 Is easy to find
As with our other documentation sections, no matter how well they are crafted, they are of no use if no one can find them. Make sure that a link to the reference guide is clear to find in a navigation bar and/or the main page.
If the reference guide is a part of a command line package, make sure that it is clear in your documentation what command you need to see it (e.g. --help
).
7.2.2 Is searchable
Users will be digging into your reference guide looking for a specific entry. Making your reference guide alphabetical is a start. If you are able to make terms searchable that’s even better, but at the very least, if your reference guide is visually easy to be scan, that can serve a similar function.
7.2.3 Is comprehensive
All items are covered in the reference guide – every. single. thing. This includes all:
- Terms
- Functions
- Arguments
- Parameters
- Defaults
- Datasets or items included in the package
- Buttons (in the case of a GUI)
The most useful entries in these reference guides…
- Not only define the item, but tell how it relates to other items (and they have links where relevant).
- Discuss all the possible inputs that can be used as well as how to decide which input fits the user’s needs.
- Make any existing defaults very clear.
- Shows the usage of that item in context – some example lines of code go a long way.
- Tries to avoid the use of jargon, but if it is absolutely necessary to use a jargon-y term it links to information about the meaning of the term.
Take a look at DESeq2’s reference guide, Love, Huber, and Anders (2014) do a great job at their entries – covering the right amounts of information and informing the user about how to decide what works for them.
7.2.4 Data formats are described
Perhaps after installation, getting data formatted correctly is one of the other very large hurdles users will need to deal with.
Ideally, your tool can use a data format that is common. But the more that your tool is particular about an odd data format, the more your documentation needs to be specific about what the odd data format looks like.
- Include example files for a positive control/example.
- Send your user to any tools they can use to convert their data format automatically.
- If its feasible, include an automatic data converter as a part of your tool.
GSEA has great descriptions of their data formats with examples of what the data formats look like.
7.2.5 Entries should have a consistent format
Consistency helps your users know what to expect and know where to find information! Each entry in the reference guide should have the same format and sections, in the same order.
Depending on the destination of your package, a consistent format may already be determined for you. Bioconductor packages have specific guidance on these reference manuals.
To recap:
7.3 Good examples of reference guides
QIIME2 has a great reference guide! Bolyen et al. (2019) cover all items and terms with lots of links to more information or related entries.
Bioconductor packages have a consistent reference guide format that the packages there adhere to which makes it easier for users to find what they are looking for once they are familiar with the format. A typical package’s reference guide looks like this.
7.4 Exercise: Create your own reference guide!
For R package documentation: Follow the advice from Hadley Wickham from the R Packages book which includes using roxygen2 package to automatically render those .Rd files!
If your tool’s destination is Bioconductor, see their specific guidance on manual pages.
For Python package documentation:
Follow the docstrings
guidance and instructions here.
For other general purposes, you can our the reference guide template to start your own reference guide either by using the markdown template directly, or navigating to the MkDocs repository you set up in the previous chapter.
References
For all cartoons:
Avataars by https://getavataaars.com/.
Icons by https://thenounproject.com/ License CC BY-NC-ND 2.0.
Emojis by OpenMoji License: CC BY-SA 4.0.↩︎