generated from jhudsl/OTTR_Template
-
Notifications
You must be signed in to change notification settings - Fork 0
/
10-other-features.Rmd
85 lines (55 loc) · 5.22 KB
/
10-other-features.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
---
title: "Other helpful features"
output: html_document
---
```{r, include = FALSE, echo = FALSE}
ottrpal::set_knitr_image_path()
```
# Other helpful features
```{r, fig.alt="Learning Objectives. This chapter will demonstrate how to: Add other helpful features that help usability of a tool. Determine which of these features are most useful for your particular context.", echo = FALSE}
ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gd436f8053d_0_0")
```
## The goal of these "other features"
There are some features that can increase the usability of your tool, but would probably not work well as standalone documentation.
The extent to which these other kinds of documentation are applicable to your software tool, is dependent on your own context and resources.
In this chapter, we will discuss these other features and when you might want to consider adding them to your set of documentation.
## FAQs
As your user base grows and you start to get recurring questions, you may want to try to head off future users asking the same questions by incorporating clarifications into your documentation.
Ideally you would make sure the most _frequently_ asked questions would be addressed in the getting started section or perhaps your how-to examples.
But, there may be other recurring questions that you don’t have a logical place to describe the answer to, but would be helpful for users to know about. In this instance, a FAQ page may be what you need.
FAQ'S can easily get disorganized and out of hand as they grow.
Try to keep similar questions underneath larger headings.
_More reading on FAQ pages:_
- [Making a killer FAQ page](https://www.socialmediatoday.com/content/10-tips-creating-killer-faq-page) [@Moon2011].
- [25 of the Best Examples of Effective FAQ Pages](https://www.searchenginejournal.com/best-faq-page-examples/267709/) [@Wilson2020].
## Cheatsheets
If your tool has a lot of items that are handy but tough to keep track of a cheatsheet may be especially helpful for your users.
Cheatsheets are like reference guides but shorter (one or two pages) and more aesthetically pleasing.
Users like cheatsheets for handy referencing!
Ideally your cheatsheet won't be identical to your reference guide but instead will highlight the most commonly used/most helpful items!
_More reading on cheatsheets:_
- For inspiration and examples of nice cheatsheets, take a look through [RStudio's cheatsheets](https://www.rstudio.com/resources/cheatsheets/) [@RStudioTeam2020].
- If you use Overleaf, there are [template cheatsheets you can use here](https://www.overleaf.com/gallery/tagged/cheat-sheet).
## Videos
Particularly, if your tool has a graphics user interface, sometimes videos can be the best way to demonstrate getting started information.
Videos are not scannable so in general, shouldn't be depended on as the main source of information.
Your users may have a quick question they want answered quickly and videos require time to watch. Users may be frustrated if the video didn't answer their question after watching it, if there is no other form of documentation.
That being said, videos are very helpful for GUI's in particular or for introducing basic concepts.
And the majority of users who like visuals will appreciate that aspect of videos.
_More reading on making videos:_
- [Creating Instructional Videos](https://www.techsmith.com/blog/instructional-videos/) [@Simon2020].
- [7 Great Tools for Creating Your Own Instructional Videos](https://helpdeskgeek.com/free-tools-review/7-great-tools-for-creating-your-own-video-tutorials/) [@Trounce2019].
- [See Galaxy's tutorial videos as examples](https://training.galaxyproject.org/training-material/topics/introduction/) [@Afgan2018].
## Forums/Knowledge Base
Forums and knowledge bases can be a handy way to keep public records of questions and answers and reduce the number of times your team has to respond to a repeated question.
Forums are mostly useful if your tool grows a big user base (hooray!) and your team has trouble keeping up with inquiries.
Advanced users may also be able to help answer questions of newer users which further frees up your team for other issues.
Making this knowledge base be searchable can reduce the support load of your team.
If you don't have the resources to host your own forum, a Slack channel could serve similar purposes or you can look into the options discussed in these articles:
_More reading on knowledge bases and forums:_
- [Knowledge Base Options](https://herothemes.com/blog/best-knowledge-base-software/) [@Herothemes].
- [Building an Online Community](https://geekflare.com/online-community-software/)[@Rehan2019].
- [A Quick Guide for Building a Successful Bioinformatics Community](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1003972) [@Budd2015].
## Exercise: Determine which (if any) of these features would work well for your tool
Now that we've discussed some of other features that are helpful for your users, think about which of these might be helpful for your own tool, keeping mind your current documentation set up, user base, and general format.
The answer might be multiple or none of these features -- only you and your team can answer this!