Help! Things have gone wrong!
Things are going to go wrong. Things are going to break. Instructions will seem vague or incomplete - or worse, I will have indeed forgotten to tell you something crucial.
Or worse, I’ve made an assumption about your understanding, and left things unsaid that needed to be made explicit. There’s a lot of this, in the digital world, in fact.
This week, you learned a bit about Git and Github. Let’s look at a question on the q-and-a site, ‘Stackoverflow’ here. Just scroll through that question, and look at some of the answers. Make a note of any terms or code or responses that make not an ounce of sense to you.
It can make you feel rather overwhelmed, rather quickly. And like most places on the internet, StackOverflow has its own culture, its own norms of expression and behaviour. People who are new can get roasted. That’s one of the reasons we have our own discord server, and a private reading group on Hypothesis: these are places for you to ask for help from a community that understands where you’re coming from because we’re all in the same headspace.
So, when things go wrong, the first thing to do is to find the community that understands where you’re coming from. I read and search StackOverflow all the time, but I rarely ask questions there. Instead, I write to trusted colleagues. And they in turn write to me.
But there are a couple of things we can do to make life easier.
Asking good questions
StackOverflow does have good advice on asking good questions. I will excerpt some of their advice:
Write a title that summarizes the specific problem… If you’re having trouble summarizing the problem, write the title last - sometimes writing the rest of the question first can make it easier to describe the problem.
Introduce the problem before you post any code [or a screenshot or a video clip]…start by expanding on the summary you put in the title. Explain how you encountered the problem you’re trying to solve, and any difficulties that have prevented you from solving it yourself.
Help others reproduce the problem [SG: post the code, post a screenshot, post a video clip walk through]
Please do this.
Every term, I receive dozens of emails with the subject line ‘help’ and the message body ‘i tried it and it doesn’t work’. Sometimes, the message will also say ‘i worked on it for 3 hrs and it doesn’t work’.
None of that is helpful. Telling me that you worked on it for 3 hours just shows me that you ignored my messages about ‘if it doesn’t come after 30 minutes, take a break, ask for help’.
Collect all of the information together, put it in a file in your repo, and share the link in discord or post the whole thing in the relevant channel.
Please, PLEASE, don’t just post something that says, ‘it didn’t work’ and then leave it at that. What’s ‘it’? What were you expecting to happen? What did you try? Show me…
Answering questions
As the course progresses, you will have many opportunities to ask for help from me and from your peers - post these in our discord server in the appropriate channel.
Sometimes, you will see questions that you can answer. A few guidelines for answering questions:
- There are many different ways to solve these issues; someone might post a different way but that doesn’t mean that either of you are necessarily wrong.
- Read the question carefully. Request clarification if there are bits that the original poster didn’t make clear - help them to ask better questions.
- Use screenshots and screenvideo (I find screencastomatic handy in this regard) to show how things worked for you.
- Provide links to useful relevant material if you know of it.
- Assume the best of everyone: not everyone has the same fluency with these machines, and it takes a while to learn the language.
Answering the questions of your peers, helping them out, is an excellent way to meet one of the course outcomes.