Skip to content

Commit a5fd3fd

Browse files
authored
Interaction guide from AAS 235 (#57)
* first draft of interaction guide * Edited format with github markdown * Change intro to highlight complement to CoC
1 parent 9b1708e commit a5fd3fd

File tree

1 file changed

+74
-0
lines changed

1 file changed

+74
-0
lines changed

drafts/interaction-guide.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
2+
**This list of recommendations was provided to volunteers for the
3+
NumFOCUS booth at AAS 235.**
4+
5+
The Astropy code of conduct (CoC) seeks to create a welcoming
6+
environment for all. This short guide focuses on common missteps
7+
in user interaction that can lead to a poor user experience. The
8+
example cases and their complementary responses are meant to train effective
9+
and respectful communication that adheres to the spirit of the Astropy CoC.
10+
11+
1. No code bashing, directly or indirectly. No scoffing, rolling your
12+
eyes, or questioning users' choices. Everyone chooses different tools
13+
for a reason. If they are not using the same tool you would, use "I"
14+
statements to tell them:
15+
16+
DO NOT SAY:
17+
> "Well, this is a photutils session so you should be using Astropy."
18+
19+
DO SAY:
20+
> "I don’t know how to do that task with IDL, but I can show you how to do it with Astropy photutils."
21+
22+
23+
2. Don’t make assumptions about users' competence or familiarity with
24+
various tools or concepts. Investigate their familiarity by utilizing
25+
a top-down approach. Direct them to perform a task, and if they are
26+
stumped, go one level deeper.
27+
28+
DO NOT SAY:
29+
> "Do you know how to use a terminal?"
30+
31+
DO SAY:
32+
> "Can you open a jupyter notebook session for me?" ... "Okay, open a terminal and type in `jupyter notebook`, then press enter."
33+
34+
3. Do not use the word "actually"
35+
36+
DO NOT SAY:
37+
> "Actually, that’s a good point."
38+
39+
DO SAY:
40+
> "That’s a good point."
41+
42+
The word "actually," in the first sentence, is "used to emphasize that
43+
something someone has said or done is surprising" (Apple
44+
Dictionary). This means you did not expect the person who was talking
45+
to have a good point, which conveys an underlying assumption about
46+
their competence. Eliminate the word "actually" from your vocabulary.
47+
48+
49+
4. If you cannot directly answer someone’s question, direct them to
50+
the appropriate online resource. If they still want your help, assist
51+
them with interpreting the documentation. If there are other people
52+
waiting, respectfully disengage.
53+
54+
DO NOT SAY:
55+
> "Just read the documentation."
56+
57+
DO SAY:
58+
> "Okay, here’s the documentation. There are some people waiting
59+
to be helped. Why don’t you take some time to read this, and when I’m
60+
done helping this other person, let me know if you still have
61+
questions."
62+
63+
64+
5. If a user insists that you help them in a way that you are unable
65+
to, find a respectful way to disengage.
66+
67+
DO NOT SAY:
68+
> "Well, you should be using Anaconda."
69+
70+
DO SAY:
71+
> "I’m sorry, I don’t know how to help you without using
72+
Anaconda." ... "Maybe some one else can help you with that task. How
73+
about asking the question on the #general Astropy Slack channel to see
74+
if anyone else can do it that way?"

0 commit comments

Comments
 (0)