From 47db7991f11a1f4e803eaf5cd331f9d6bb2de244 Mon Sep 17 00:00:00 2001 From: Gareth Coles Date: Mon, 26 Feb 2018 18:49:44 +0000 Subject: Help page #z62n (#25) * Help page and misc improvements Committing so I can go home >:| * Changes for @lmn * Rephrase first paragraph * Rephrase questions so they aren't all about discord.py * Remove _every single header_ on the help page from the nav * Unit test the help route * Small styling fixes * Add page-specific classes to body element * Clean up section padding * IndexView -> HelpView * Remove unnecessary path in test --- templates/main/base.html | 16 +- templates/main/help.html | 459 +++++++++++++++++++++++++++++++++++++++++ templates/main/index.html | 2 +- templates/main/navigation.html | 13 +- 4 files changed, 475 insertions(+), 15 deletions(-) create mode 100644 templates/main/help.html (limited to 'templates') diff --git a/templates/main/base.html b/templates/main/base.html index 96a25554..3da4715e 100644 --- a/templates/main/base.html +++ b/templates/main/base.html @@ -12,15 +12,17 @@ {% endblock %} - + {% include "main/navigation.html" %} {% if current_page != "index" %} -
-
-

- Please note: this site is under construction. What you see now may be vastly different - from the final project state. Feel free to chat to us on Discord if you're curious! -

+
+
+
+

+ Please note: this site is under construction. What you see now may be vastly different + from the final project state. Feel free to chat to us on Discord if you're curious! +

+
{% endif %} diff --git a/templates/main/help.html b/templates/main/help.html new file mode 100644 index 00000000..d3084f8b --- /dev/null +++ b/templates/main/help.html @@ -0,0 +1,459 @@ +{% extends "main/base.html" %} +{% block title %}Getting Help{% endblock %} +{% block content %} +
+
+
+

+ Getting Help + + + + +

+

+ Everything's exploding, customers are complaining, management's on the fritz! +

+

+ This document is intended to provide you with the information you need to get help as quickly and + effectively as possible. If you're stuck on a problem or you just don't understand something, feel + free to join us and ask for help - you can use this as a reference when forming your question. +

+

+ Much of this document is based on the sentiments expressed by Eric Steven Raymond and Rick Moen + in their essay, How To Ask Questions The Smart Way. + Please note that the essay is very long and may be considered rude by some. Additionally, the people + behind that essay are in no way affiliated with us - please do not bother them with your Python + problems. +

+

+ Before You Ask + + + + +

+

+ Take stock of your problem, and do your homework. +

+

+ Before you ask your question, there are a few things you can do to find an answer on your own. + Experienced developers will do the following: +

+
    +
  • Read the official documentation for whatever you're working with
    • +
  • Use a debugger to inspect your code
    • +
  • Do some research online - for example, on Stack Overflow
    • +
  • Read the source code for whatever you're working with
    • +
  • Search the message history of the help channels
    • +
+

+ Essentially, doing your research is the first step towards a solution to any problem. If your + problem isn't extremely general, we're going to be doing exactly these steps ourselves when you ask, + so doing the legwork beforehand saves everyone a lot of time. +

+
+
+
+
+
+
+

+ + + Creativity requires input, and that's what research is. You're gathering material with which to + build. +

+ + Gene Luen Yang + +
+
+
+
+
+
+

+ If you're an absolute beginner, take a moment to step back from the problem. + Have you read a book or done a + tutorial? There's a huge amount of resources out there, many of which are going to help you a lot more than + us answering the beginners' questions for you. If you're following a tutorial, book or course and + you don't understand something, then that is the correct time to ask a beginners' + question. Of course, we won't turn you away if you do have a beginners' question — by all + means, + come to us if you do have a problem. +

+

+ Have you read the official documentation for the module or technology you're working with? The + official Python 3 docs are a fantastic and valuable + resource, so if you're using a bundled module, your first port of call should be there. If you're + using a third-party library, often they will have some official documentation uploaded somewhere + — + try having a Google around, or take a look at PyPi in case they've + linked it from there. +

+

+ If you can't find the documentation or you find it lacking, the next place to look is the source + code. + Grab a decent IDE (we recommend PyCharm Community) + and a coffee, download a copy of the project and open it up, and get to browsing! +

+

+ If you're still confused, try searching the Internet for people that have already had the same + problem. Often, you won't be the only person to have encountered the issue you're dealing with - more often + than not, you'll find a GitHub ticket or a StackOverflow question along with a fix or answer to your + question already posted. +

+

+ If none of the above helps you or you're lost, scared and alone, feel free to continue on to the + Discord server. You can use the search feature (the at the top right) to check + whether someone else has asked your question recently, or just feel free to pick one of the help channels + and ask your question. +

+

+ A Good Question + + + + +

+

+ Thank you for helping us help you help us all. +

+

+ When you're ready to ask a question, there's a few things you should have to hand before forming + a query. +

+
    +
  • + A code example that illustrates your problem +
      +
    • If possible, make this a minimal example rather than an entire application
      • +
    +
    • +
  • Details on how you attempted to solve the problem on your own
    • +
  • Full version information — for example, "Python 3.6.4 with + discord.py 1.0.0a"
    • +
+

+ Your question should be informative, but to the point. More importantly, how you phrase your + question + and how you address those that may help you is crucial. Courtesy never hurts, and please type + using correctly-spelled and grammatical language as far as you possibly can. +

+

+ When you're inspecting a problem, don't be quick to assume that you've found a bug, or that your + approach is correct. While it helps to detail what exactly you're trying to do, you should also + be able to give us the bigger picture - describe the goal, not just the step. Describe the problem's + symptoms in chronological order - not your guesses as to their cause. +

+
+
+
+
+
+
+
+

+ Bad Questions +

+
+
+

+ Good Questions +

+
+
+
+
+

+ Where can I find information on discord.py? +

+

+ This question suggests that the person asking it hasn't done any research, or even a simple + Google search. +

+
+
+

+ I used Google to try to find more information about "discord.py 1.0.0a", but I couldn't + really + find anything useful. Does anyone know where I might find a guide to writing commands + using this library? +

+
+
+
+
+
+
+
+
+
+
+
+
+

+ Pillow puts my text at the bottom of the image instead of where I wanted it. Why is it broken? +

+

+ This question assumes that the problem is with Pillow itself, and that it isn't + the questioner's fault. It also doesn't provide enough information on the problem. +

+
+
+

+ Pillow appears to insert text at the bottom of the image if the given X coordinate is negative. + I had a look at the documentation and searched Stack Overflow, but I couldn't find any + information on using negative coordinates to position text. Has anyone attempted this? +

+
+
+
+
+
+
+
+
+
+
+
+
+

+ I'm having some trouble writing a YouTube random URL generator - can anyone help? +

+

+ This question provides no information on the problem, and asks for help in a way that isn't + engaging - some people will find this annoying, as answering your question is guaranteed + to result in another question. +

+
+
+

+ My YouTube random URL generator appears to be returning false positives for tested URLs, + stating that a URL points to a real video when that video doesn't actually exist. Obviously + there's some issue with how this is checked, but I can't put my finger on it. Is there anything + I can check? +

+
+
+
+
+
+
+
+
+
+
+
+
+

+ I want to share a YouTube video with my friend, but the video doesn't move when I print the page. + How do I make the video move? +

+

+ This question assumes a specific (wrong) approach, and isn't open-ended enough to account for + the possibility of a better solution. +

+
+
+

+ I'm attempting to figure out the best way to share a YouTube video with my friend that doesn't + have the Internet at home. I can't think of a better approach than printing the page, which + obviously doesn't help much given that the video doesn't move on the paper - can anyone think + of a better approach to this? +

+
+
+
+
+
+
+
+
+
+
+
+
+

+ I was given this assignment by my teacher, but I'm not sure how to approach it. Does anyone + have any ideas? +

+

+ This question is clearly a homework question. Homework is supposed to challenge you, and we + will not provide solutions to homework. Instead, ask a more general question. +

+
+
+

+ I have a list of numbers - how do I calculate how many of them are even? Is there a way + to remove all the odd numbers from my list? Are there quick ways to find the average of + a list of numbers, or add them all together? +

+
+
+
+
+
+
+
+

+ Interpreting Answers + + + + +

+

+ Wow, rude. +

+

+ Programmers have a certain set of mannerisms. While we all try to be as courteous with our replies + as possible, occasionally it may seem as if a helper is annoyed or disinterested in your question. + This isn't personal - it's just part of our culture. Remember that the people you're asking for help + are humans and that they're here voluntarily, in their free time. +

+

+ If you've asked a question and you're told to read the documentation or search the web, you should + do that. When this happens, it's often the case that the person responding has the information you need + open in their web browser and either thinks that it's very easy to find, or that you would learn + more from seeking out the source of the information yourself. If you've already done this, you should + tell us by including it in your question! +

+

+ If you don't understand an answer, don't immediately bounce back and demand clarification. Use the + tools available to you (the internet, documentation, source code) to help you understand the answer, and + if you still can't figure it out, ask for clarification and provide any relevant information you learned + during your research. +

+
+
+
+ +
+
+
+

+ + + Successful people ask better questions, and as a result, they get better answers. +

+ + Tony Robbins + +
+
+
+ +
+
+
+

+ Much of what looks like rudeness within programming communities is not intended to be offensive and + it's often just a product of the down-to-earth, direct style of communication that is typical in + a community that is more concerned with solving problems than anything else. If you perceive + rudeness, try to react calmly. If a user really is acting out, then chances are that a member of staff will + call them out on it. If this doesn't happen, contact a member of staff directly and they will try + to clarify this with you. +

+

+ It's okay to mess up. It happens to all of us. That said, if you mess up badly enough, it's likely + that you will be corrected there and then, in public and with a verbal scalpel. Take this as a + learning experience and don't let it get to you - this is a common and appropriate response in + many programming circles. Community standards do not maintain themselves - they're maintained by + people applying actively them, visibly, in public. +

+ +

+ What Not To Ask + + + + +

+

+ Sample questions to avoid as much as possible. +

+ +

+ Can I ask a question? +

+

+ Yes. Always yes. Just ask it. +

+ +

+ Can I use str() on a discord.py Channel object? +

+

+ Try it yourself and see. Experimentation is a great way to learn, and you'll save a lot of time by + just trying things out. Don't be afraid of your computer! +

+ +

+ My code doesn't work +

+

+ This isn't a question, and it provides absolutely no context or information. Depending on the moods + of the people that are around, you may even find yourself ignored. Don't be offended by this - just + try + again with a better question. +

+
+
+
+ +
+
+
+

+ + + So much of life isn’t about having the right answer; it’s about knowing the right question. +

+ + Duane Hewitt + +
+
+
+ +
+
+
+

+ Can anyone help me break into someone's Facebook account?
+ Can anyone help me download anime from this streaming site's listing page?
+ How do I write a virus? +

+

+ We will absolutely not help you with hacking, pirating, or any other illegal activity. A question + like this is likely to be followed up with a ban if the person asking it doesn't back down quickly. +

+ +

+ Can I send you a private message? +

+

+ No. We do not provide one-on-one tutoring - you can hire someone locally if you really need that. We + also prefer that questions are answered in a public channel as it means that everyone else present + is able to learn from them. If you're working with code that you are unable to disclose for any + reason, you should try to make your question more general and write a separate, small piece of code + to illustrate your problem. +

+ +

+ Can you help me over Teamviewer? +

+

+ No. We will not help you by accessing your computer remotely, or watching a video stream of your + problem, unless the problem is something that inherently requires that. The reason for this is that + our time is limited, and watching a video or participating in a screen-sharing session means that we + have to focus on you, instead of being able to deal with other people while you're figuring out an + answer. If your problem is graphical and you can't adequately describe it without a visual, take a + screenshot or provide a short screen recording to illustrate your problem. +

+
+
+
+{% endblock %} \ No newline at end of file diff --git a/templates/main/index.html b/templates/main/index.html index 258b7a7c..d8c5febc 100644 --- a/templates/main/index.html +++ b/templates/main/index.html @@ -1,7 +1,7 @@ {% extends "main/base.html" %} {% block title %}Home{% endblock %} {% block content %} -
+

Python Discord diff --git a/templates/main/navigation.html b/templates/main/navigation.html index 88fc3585..8a1e9a6a 100644 --- a/templates/main/navigation.html +++ b/templates/main/navigation.html @@ -1,4 +1,4 @@ -
+