Skip to content

Latest commit

 

History

History
121 lines (102 loc) · 5.46 KB

question-template.md

File metadata and controls

121 lines (102 loc) · 5.46 KB
Raw
name about title labels assignees
Question template
Use this template for all questions

Please read this before posting.

We ask you to include certain information when you ask a question and to search already existing similar questions and try their solutions before posting. The reason for this is that we want to be able to help as many students as possible to solve their issues. If you just include a screenshot and title your question "Help", we have to spend time trying to figure out what you actually want help with instead of helping, we can't copy your code to troubleshoot it on our machines, and other students with related issues can't find your question since text in the screenshots is not searchable. This takes time away not only from yourself, but also from your classmates, and if many students do this we will have to leave some questions unanswered.

Troubleshooting code can be tedious and sometimes even frustrating, so we have designed this issue template to streamline the support you receive. You can find an abbreviated structure for each question in the summary section below and more details on how to ask good questions in the following section. If anything is unclear, don't hesitate to reach out to us either here or via the TA email.

A nicely rendered version of this template can be found here https://github.com/BME1478H/Winter2020class/blob/master/.github/ISSUE_TEMPLATE/question-template.md

Summary

  1. Create a descriptive title so it is clear what you are asking.

  2. Paste any code your are executing as text.

    • If your code includes functions or classes, also include their definitions.

    • Use markdown code blocks for proper indentation and syntax highlighting by adding a line with three backticks before and after your code like this (if you are viewing the rendered version, you can see that this has been formatted as a code block):

      # Include your code here
for i in range(3):
    print(i)

  3. Describe what you don't understand or what went wrong, including any error message and traceback message.

Details

Click the "Preview" tab above to view the rendered version of this issue template.

Delete this text after you have read through it and are replace it with your question. This template will appear every time you open a new issue, so you don't need to memorize it.

In this class, we're using GitHub issues as the forum for asking and responding to questions. Knowing how to use GitHub is often required when collaborating on bigger projects, especially those that are open source and maintained by remote teams. It is also a great skill for asking effectively on StackOverflow, the biggest Q&A site for programming related questions.

When submitting an issue, please follow the template below. This will help you practice how to be an effective collaborator and the included information will ensure that you get help as quickly as possible.

  1. Write the tile as a summary of your issue. Think about what you would want the title to say if you were searching the issue list for help. Just "Error" or "Question" is not helpful, but "How to list content in a folder?" is. If your issue relates to a specific assignment question, you can preface the title with that information, but still include details about your particular problem, e.g. "A1Q1 'Command not found' when trying to run Python"
  2. Introduce the problem by briefly describing what you want to do.
  3. Show what you have tried, explain what you expected to happen, and what went wrong. It is often critical that the person helping you can reproduce the problem, so include both the code or command you tried to run and the error message as described in this guide on how to create a Minimal Reproducible Example.
    • Text is preferred over a screenshot since it is easy to copy and paste, which facilitates reproducing your problem. If a screenshot is needed we will ask for it specifically.
    • Inline code should be surrounded by backticks for clarity, which will be formatted like this on GitHub. Longer blocks of code with multiple lines should be surrounded by triple backticks. Please see this link for how to format comments on GitHub in general using the markdown syntax.
  4. Include which operating system you are using and which version of the troubling program your are on, e.g. Win10, Python 3.8.
  5. When your problem is solved, close the issue. If you found the solution yourself, post it in a comment before closing, so that others can find it.

That's it! Feel free to help each other if you see a question that you know the answer to. And don't worry if you have a question that you don't think fits in the format about, go ahead and post it and we will try to figure it out! You can read more about how to ask great question in this StackOverflow post. As a final note, remember that this GitHub issue list is public, so if you have a sensitive question, please send an email to the TA email address instead.

Remebmer to delete this text after you have read through it and are replace it with your question. This template will appear every time you open a new issue, so you don't need to memorize it.