-
Notifications
You must be signed in to change notification settings - Fork 3
/
03_asking_for_help.Rmd
194 lines (106 loc) · 20.1 KB
/
03_asking_for_help.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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
# How to ask for help
In our area of work, we will frequently run into code error messages as well as work with concepts that span multiple research fields including neuroscience, genomics, and bioinformatics. Thus, it is completely natural that we'll need to ask others for help. We do this so frequently, that we end up developing skills for searching for the information that we need. Most of the times, we can spend a bit of time ourselves searching for a solution as described in more detail in ["you must try, and then must ask"](https://blogs.akamai.com/2013/10/you-must-try-and-then-you-must-ask.html). Though at some point, we will ask others for their direct input.
Many of the communication tools we use for asking for help are text-based. It can be hard to convey jokes, so sometimes it's best to refrain from making jokes in order to prioritize a clear exchange of ideas. You should also be respectful of everyone's time and with the words you choose. For example, see what [Jim Hester](https://twitter.com/jimhester_) has to say about issue titles:
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">Take time⌚️to think about your issue titles!!!<br><br> xyz is broken<br><br>vs<br><br> xyz fails with malformed input<br><br>The former puts the maintainers in a foul mood 😡<br><br>Issues should be requests 💐 rather than demands 🔨</p>— Jim Hester (@jimhester_) <a href="https://twitter.com/jimhester_/status/1348742632491646976?ref_src=twsrc%5Etfw">January 11, 2021</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
Actually, Jim Hester keeps providing excellent advice, so you might want to check this table he made and shared on [Twitter](https://twitter.com/jimhester_/status/1390021499797577731?s=20).
<script src="https://gist.github.com/jimhester/9b5461108f93162e15c42684076de82f.js"></script>
We highly recommend that you watch [Jenny Bryan](https://twitter.com/JennyBryan)'s RStudio Conf 2020 keynote talk titled "Object of type ‘closure’ is not subsettable" available through [RStudio's website](https://www.rstudio.com/resources/rstudioconf-2020/object-of-type-closure-is-not-subsettable/). You can find all related links from her talk through [GitHub](https://github.com/jennybc/debugging#readme).
<p><a href="https://www.rstudio.com/resources/rstudioconf-2020/object-of-type-closure-is-not-subsettable/?wvideo=3eryv8gcor"><img src="https://embed-ssl.wistia.com/deliveries/2e2c4f025a70aaa1659fa66786570766f9f0f11a.jpg?image_play_button_size=2x&image_crop_resized=960x540&image_play_button=1&image_play_button_color=4287c7e0" width="400" height="225" style="width: 400px; height: 225px;"></a></p><p><a href="https://www.rstudio.com/resources/rstudioconf-2020/object-of-type-closure-is-not-subsettable/?wvideo=3eryv8gcor">Object of type ‘closure’ is not subsettable - RStudio</a></p>
Ultimately, some coding issues are complex. Here are some tips on some strategies for resolving complex coding problems.
<iframe width="560" height="315" src="https://www.youtube.com/embed/xUSEippbXBc" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## General guidelines
In general, please follow these [Bioconductor composing guidelines](http://bioconductor.org/help/support/posting-guide/#composing) when asking for help.
### Avoid screenshots
While a screenshot might convey a lot of information, it is challenging to extract the relevant code in order to reproduce the error being described. Thus text is strongly encouraged over screenshots.
### Reproducible code
The function call and the associated error message are frequently not informative enough for others to determine the root of the problem. You should aim to include the `traceback()` information in R or equivalent in other languages which provides more detail on what happened. However, even the `traceback()` information might not be enough, which is why you should definitely include the code for re-creating any objects you used in the function call. One simple way to do so is to include a _permalink_ to a script you have version controlled on GitHub.
### Use reprex
Use the `r BiocStyle::CRANpkg("reprex")` package for making small reproducible examples. Check our LIBD rstats club session on `reprex` to learn more about it.
<iframe width="560" height="315" src="https://www.youtube.com/embed/8bBo3B7N8YQ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
### Use Markdown syntax
Either on Slack or GitHub, you can use some Markdown syntax features. In particular, you can use in line code formatting (1 back tick) and multi-line code formatting (3 backt icks). On GitHub, you can also use the html code tags `<details>` and `</details>` to hide long output, which is useful for showing the R session information. That is, the output from `r BiocStyle::CRANpkg("sessioninfo")`. As an example, check [this `BayesSpace` issue](https://github.com/edward130603/BayesSpace/issues/71#issue-1123372304).
### R session information
Use the `r BiocStyle::CRANpkg("sessioninfo")` package to provide the full details of your R session. Some errors might have already been addressed in newer versions of R packages or R versions. Providing that information makes it easier for others to help you.
## Learning from our search history
We have occasionally used a team activity called "learning from our search history" described [in this blog post](https://lcolladotor.github.io/2020/02/12/learning-from-our-search-history/). One of the goals of this activity was to learn some search skills each of us has that are typically not taught. Another goal was to show that we all search for more information all the time because no one, not matter how experienced, knows all the answers.
## Bioconductor Support website
We use [Bioconductor](http://bioconductor.org/) R packages for most of our work because they contain a lot of useful functions for the type of work we do. Bioconductor packages can be under active development and changing frequently. Plus, some are challenging to understand how to use. For these and other reasons, Bioconductor has a [**BioC Support Website**](https://support.bioconductor.org/).
You will need to make an account before you can ask (or answer) a question. Once you do, you will need to use [tags](https://support.bioconductor.org/t/) for labeling your question: typically with the tag that matches the Bioconductor package you are using. When you start to ask a new question, you will see a link to the new [posts guide](http://bioconductor.org/help/support/posting-guide/#composing) and the [tutorial for asking questions](https://support.bioconductor.org/p/117436/).
You should try your best to follow those guidelines in order to make it easier for others to help you. Remember that you should follow the [Bioconductor code of conduct](http://bioconductor.org/about/code-of-conduct/).
## RStudio Community website
Since we use R so much, we also use R packages developed by RStudio developers. One great and friendly website for asking for help with all things that are related to R (but maybe not so much related to Bioconductor) is the [**RStudio Community website**](https://community.rstudio.com/). This website is particularly useful if you have questions about RStudio itself or the `tidyverse` R packages.
If you want to get a summary of new posts that might be relevant to you, you can sign up for weekly email updates. On this website, there's a strong preference for using the `r BiocStyle::CRANpkg("reprex")` package for making small reproducible examples. Check our LIBD rstats club session on `reprex` to learn more about it.
<iframe width="560" height="315" src="https://www.youtube.com/embed/8bBo3B7N8YQ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## GitHub
Frequently, we work with software that is cutting edge and under active development. Many people share their code through websites like [Bitbucket](https://bitbucket.org/), [GitLab](https://about.gitlab.com/), and most frequently, through [**GitHub**](https://github.com/).
At LIBD we have a GitHub organization account [github.com/LieberInstitute](https://github.com/LieberInstitute). Think of it as our code library. As described in more detail in this video, you can search our code base, which might be useful to see actual examples on how we've used functions from specific R packages or other tools. If you work at LIBD, email Bill Urich so he can add you to the organization account, thank you!
<iframe width="560" height="315" src="https://www.youtube.com/embed/vI2H59hKdQY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## GitHub issues
Most open source projects on GitHub have an **issues** page where you can interact directly with the developers of the software you are using. Note that most open source software developers are not payed to provide support, and their time might be very limited. As such, you should try very hard to provide all the information the developers need in order to help you. This is a time consuming process, but it can help you learn more too, and sometimes even resolve the problem yourself.
Some GitHub repositories have _issue templates_ such as [`lcolladotor/biocthis`](https://github.com/lcolladotor/biocthis/issues/new?assignees=&labels=&template=issue_template.md&title=%5BBUG%5D+Your+bug+or+feature+request) that will tell you a bit more of what information you should provide to make it easier for others to help you out. Others like [`rstudio/blogdown`](https://github.com/rstudio/blogdown/issues/new) will ask you to fill a few checkmarks before submitting your question.
Again, [Jim Hester](https://twitter.com/jimhester_) has some useful advice.
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">Writing issues with too much description is nearly as bad as too little. 𐄷<br><br>Often the real problem is something completely different then what the reporter spent so long describing. 🤔<br><br>One reproducible example is worth 1,000 words. 🖼</p>— Jim Hester (@jimhester_) <a href="https://twitter.com/jimhester_/status/1350076918520045568?ref_src=twsrc%5Etfw">January 15, 2021</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
## Mailing lists
Eventually, you might need to ask for help through specific e-mail mailing lists. This is more common the closer you get to source code. Some of the mailing lists we use frequently are listed below.
### JHPCE
If you need help with R and JHPCE, you might find this video and [companion notes](https://docs.google.com/document/d/14ax6UIlgFGnrZSR1HQ-2vLYhCYLXAGRiib5edMhxLGA/edit) useful.
<iframe width="560" height="315" src="https://www.youtube.com/embed/-6sZyp0hNwU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
#### bithelp
This is the main mailing list for asking for help with all things related to [JHPCE](https://jhpce.jhu.edu/). The JHPCE admins plus some JHPCE users such as myself and Kasper Daniel Hansen receive these emails and might reply back. You can sign up to receive these emails too if you want. Or if you want to check the previous emails, check the [**bithelp website**](https://lists.johnshopkins.edu/sympa/arc/bithelp). Before you ask for help, check the JHPCE website since there are several guides there already that might answer the question you have in mind.
#### bitsupport
This is the main mailing list for all things related to [**JHPCE admin**](https://jhpce.jhu.edu/contact/) requests. For example, if you need help with getting your password reset or changing your default JHPCE user group.
### Bioc-devel
This is the mailing list where all Bioconductor package authors are subscribed to. It's sole purpose is to help current and new Bioconductor package authors. If you have questions about how to use a Bioconductor R package, use the Bioconductor Support website **only**. However, if you do have questions about R package development, then check out [**bioc-devel**](https://stat.ethz.ch/mailman/listinfo/bioc-devel) and its archives.
You might also like this video on some specific feedback about R/Bioconductor package development. Here are some [companion notes](https://docs.google.com/document/d/1jrK3av1MZYyovcRLjL6mwI_TUwf067-Wi3oerB3HbA8/edit).
<iframe width="560" height="315" src="https://www.youtube.com/embed/boHzS5H2YLc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
If you are getting started with R/Bioconductor package development, then this video explaining [`biocthis`](https://bioconductor.org/packages/biocthis/) might be useful as well. Here are the [slides](https://speakerdeck.com/lcolladotor/making-bioc-packages-with-biocthis).
<iframe width="560" height="315" src="https://www.youtube.com/embed/aMTxkYsM-8o" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
### R-Sig-Mac
Some mailing lists are very specific to what they serve. There are several of these mailing lists related to the R source itself, for sample [**R-SIG-Mac**](https://stat.ethz.ch/mailman/listinfo/r-sig-mac) which is useful if you are compiling R in macOS, and only for questions related to that. This is a rare situation for us, but for some situations, this is where you can find the latest information and reach the experts on this topic.
## Slack
Within our team and collaborators, we use [Slack](https://slack.com/) extensively. If you are new to Slack, you might want to read this [blog post](http://lcolladotor.github.io/2018/06/19/using-slack-for-academic-departmental-communication/#.X4nr0NBKguU) that I co-authored with [Stephanie C Hicks](https://twitter.com/stephaniehicks). In that blog post, we talk about some important Slack settings that will make it easier to keep your work-life balance in check.
Slack is organized in _Workspaces_. Each of them is either free or payed, depending on the group. We mostly use the JHU Genomics Collective Slack workspace, which is a payed workspace. Meaning that we have access to all Slack-related goodies, like integrations with GitHub, Google Calendar, Google Docs, email, etc. Below you can find more information about the differnet Slack workspaces we use.
### JHU/LIBD
#### JHU Genomics Collective
This is our main Slack workspace. Just like `git` commit messages, channels are cheap. The idea is to make one channel per project. Sometimes we'll add team members to a channel even if they are not primarily working on the specific project (maybe we have a question we want to ask them or we are working in something similar in another project). Team members not primarily involved in the project should feel free to **mute** the channel. However, by being a part of the channel, they can then see images and code that we are working on, which in some situations can be useful. For example, maybe we figured out how to make a new `plotly` interactive graph in one channel, then others who are curious can get access to that knowledge and incorporate it into their projects.
If you need help use:
* [**libd_helpdesk**](https://jhu-genomics.slack.com/archives/CUYHWV7AA): for asking general questions to all team members and LIBD collaborators
For team logistics, our channel is:
* [**libd_team_lcolladotor**](https://jhu-genomics.slack.com/archives/C01AD6PQHNW): meeting reminders, papers we'll discuss and other team logistics
The remaining main Slack channels are:
* [**libd_alumni**](https://jhu-genomics.slack.com/archives/C01BHLRSPGQ): for all LIBD past and current members
* [**libd_dsgs**](https://jhu-genomics.slack.com/archives/C01AJSG6MSA): for the [DSgs-guides](#dsgs-guide-team-members)
* [**libd_general**](https://jhu-genomics.slack.com/archives/G01BNQHMTGX): for all current LIBD members that are on the JHU Genomics Slack workspace
* [**libd_genomics_martinowich**](https://jhu-genomics.slack.com/archives/C015GNM7JSC): a shared channel with the Martinowich lab Slack workspace
* [**libd_pkgs**](https://jhu-genomics.slack.com/archives/C2G0ZFDSR): for software (mostly R packages) we are making that is not specific to a particular project
* [**libd_rstats_club**](https://jhu-genomics.slack.com/archives/C9KTKPEGM): for the LIBD rstats club
There are also a set of public channels that we use frequently:
* [**conferences**](https://jhu-genomics.slack.com/archives/C0703QKUN)
* [**general**](https://jhu-genomics.slack.com/archives/C029RHR0F)
* [**genomics_seminar**](https://jhu-genomics.slack.com/archives/C08MZFZKJ): [Genomics at JHU seminars](https://twitter.com/GenomicsAtJHU?s=20)
* [**jhpce**](https://jhu-genomics.slack.com/archives/C074W8800): JHPCE users, though also check the [`bithelp`](#bithelp) and [`bitsupport`](#bitsupport) mailing lists
* [**jhu_papers**](https://jhu-genomics.slack.com/archives/C9JGFTKT2): where we announce papers with JHU authors
* [**joint_group_meeting**](https://jhu-genomics.slack.com/archives/CC4C0BYGH): a JHU bi-weekly meeting led by Steven Salzberg and JHU colleagues. This is a great meeting to learn about methods work being done across Hopkins for genomics data analysis.
* [**r-ladies**](https://jhu-genomics.slack.com/archives/CAV89BNFK)
* [**random**](https://jhu-genomics.slack.com/archives/C029RHR0H)
* [**rstats**](https://jhu-genomics.slack.com/archives/C0DAQFGMU): major R announcements and other goodies
#### Martinowich
This is the LIBD Slack workspace used by the teams led by Keri Martinowich, Kristen Maynard, and Stephanie Page. Several of us work closely with them on some projects.
#### LIBD Neuropathology
This is the LIBD Slack workspace used by the Neuropathology team. We use it to interact with Amy Deep-Soboslay, Ran Tao, and their teams.
### Bioconductor
One very useful public Slack workspace is the Bioconductor one. You can join for free through [bioc-community.herokuapp.com/](https://bioc-community.herokuapp.com/). If you join this Slack workspace, please introduce yourself on the **introductions** channel. You mgith also be interested in channels such as:
* **biocYYYY** where `YYYY` is the given year, which is the main channel for that year's Bioconductor conference. For example, `bioc2020`.
* [**containers**](https://community-bioc.slack.com/archives/CH9H1QX5W) to learn more about the Bioconductor Docker images
* [**developers_forum**](https://community-bioc.slack.com/archives/CLUJWDQF4) for learning about the Bioconductor Developer's forum (typically held once per month)
* [**jobs**](https://community-bioc.slack.com/archives/CMC6T5KJ8) for job announcements
* [**spatial**](https://community-bioc.slack.com/archives/CR1BLV821) for spatial transcriptomics and related technologies
### R-Ladies Baltimore
Another public Slack workspace is the one run by [R-Ladies Baltimore](https://rladies-baltimore.github.io/), a local chapter from R-Ladies Global. This Slack workspace is mostly active during the meetup sessions. Check out their [Meetup page](https://www.meetup.com/rladies-baltimore/) for more information.
### Miscellaneous
I'm a part of a few more Slack workspaces, though not all of them are public.
* **JHU Biostatistics**: for members and alumni of the JHBSPH Biostatistics department.
* **rOpenSci**: for members of [rOpenSci](https://ropensci.org/)
* **CSCCE**: from the [Center for Scientific Collaboration and Community Engagement](https://www.cscce.org/) which is useful if you want to learn more about community engagement
* **CDSB**: the [Community of Bioinformatics Software Developers](https://comunidadbioinfo.github.io/) (in Spanish) which I co-founded in 2018 and through which we organize R workshops to help grow the community of R/Bioconductor developers in Latin America
* **LatinR**: a public Slack workspace related to the [LatinR conference and community](https://latin-r.com/en), whose goals are overlaping with those from CDSB