Reporting issues effectively

It happens very often that people are looking for help on some topic, and they find it's hard to get a good answer. In this article, i'll share a few tips that make it easier to pose a good question, that'll get you results quicker.

It happens very often that people are looking for help on some topic, and they find it's hard to get a good answer. For example, I see questions like this a lot:

Hi, i'm doing the following and it doesn't work. Can you tell me what's wrong? {% for foo in bar %}{{ qux }}{% endif %}

Now, there's a few things that make this question hard to answer:

  • What does "doesn't work" mean? Does it produce something unexpected? Does it do nothing? Does the user get a helpful error?
  • When somebody looks at that bit of code, they have no clue what it does or what it's supposed to do.

Usually we can figure out what's going on and we can help the user, but it takes a bit of back and forth. We might've been able to help them a lot faster, if we would've gotten all the needed information straight away. If you're asking a question, you should keep in mind that the person on the other side has no context at all about what you're trying to do. To pose a good question that allows someone to quickly grasp what the problem is, use the following guidelines:

  • Briefly explain what you're trying to achieve.
  • Tell what you've attempted, and what the expected outcome of that was.
  • Show what the actual outcome was.

So, in the case of the example above, a much improved way to ask the question is:

Hi! I'm trying to make a list of links from this field I've added to my Page Contenttype. The name of the field is linklist and I'm doing the following, hoping to get separate links: {% for item as linklist %}{{ qux }}{% endif %} Instead, I'm getting the following error:

"Unexpected "endif" tag (expecting closing tag for the "for" tag defined near line 11)."

If you do this, you allow somebody to help you more efficiently. All the information is there, for someone to tell you "You should use 'endfor', instead of 'endif'.". Of course, this is a very simple example, but the main idea stands: The more relevant and concise information you provide, the better the responses will be.

Additionally, it often helps a great deal to provide screenshots when something goes wrong. An experienced developer can often spot a lot of potential gotchas that might not seem apparent to you. And, the more context you show, the better. For example, this is not very helpful:

I got a "SyntaxError"

This is slightly better, but still pretty bad:

This, on the other hand, is incredibly helpful:

It tells the person who's trying to help so much things that might not be obvious. It shows where the error occured (in the listing.twig template). It shows that it's the "main" error, and not something that happens as a side-effect of a previous error. And it makes it clear what the line with the problem is, in context.

Finally, it might be useful to provide information about the constraints. Of course this depends on the problem you're facing, but it can be very helpful to specify exact versions of - For example - PHP, Bolt version, Browser make, and which database and operating system you're using.

In closing: Please keep these tips in mind, if you're posting a question. The easier you make it for someone to understand the problem you're facing, the quicker you'll get a helpful response.

News Help Support

Permalink - Written by Bob on June 17, 2020.

Setting up a local development environment »