The art of asking great questions

1

Why this post?

Because creating informative and well structured questions:

  • Will diminish the need for repeating replies asking for clarification.
  • Will reduce the valuable time and effort spent by questioner and answerer.
  • Will add valuable information to the knowledge base this forum is.
  • And most importantly, it will increase your chances to get a helpful response.
    Badly formulated questions are often ignored…

NB. Any feedback/suggestions are welcome via DM.

Content:

  • Premium products have dedicated support
  • We are all unpaid volunteers
  • Search first, ask later
  • Provide context for your question
  • Sum up your question in a clear title
  • Create a minimal reproducible example
  • Avoid using code screenshots
  • Share what you’ve already tried
  • Format, lint and document your code snippets
  • Keep track of your question
  • Refrain from cross-posting
  • Other available channels

Premium products have dedicated support

All Premium product related questions/issues should be directed at Premium Products. You’ve paid to get support from the developers themselves.

We are all unpaid volunteers

Please understand that you will have a better experience getting solutions if you respect that members of our community want to help you, but they do so voluntarily.

It will be appreciated if you show you’ve spent time on the question to minimise the time needed by the volunteers.

As with most forums, ill formed questions tend to be ignored. So, you can do yourself a favour by creating clear questions containing all relevant details.

Search first, ask later

Search before asking a question. The question might have been asked before, and/or may have been documented.

  • Search this forum.
  • Search for known issues at the repo of relevant theme/plugin. The link to the repo can be found in Admin and in the blueprints.yaml of the theme/plugin.
  • Search the web at large.
  • Read the README of the relevant theme/plugin at its repo.
  • Consult the documentation of Grav
  • Sharing a link when you refer to relevant information makes it easier for the reader.

Provide context for your question

Context helps people understand your question better, because they’ll know what situation you’re dealing with. The better the context, the higher the chances you’ll get an answer, and it reduces anoying back and forth replies asking for clarification.

Many questioners often overlook these details despite their importance.

Relevant context should contain:

  • A clear explanation of what you are trying to achieve and why.
  • Theme being used (include link to repository).
  • Plugins involved (include link to repository).
  • Your production and/or development environment might be relevant.
  • Errors found:
    • In logs/grav.log in the root folder of Grav
    • In logs from Apache
    • In console of Developer tools of browser (Ctrl+Shift+I in Chrome)
  • But also your skills level on Grav, PHP, Twig, Javascript etc. might help the reader to formulate a suitable answer.

Don’t forget to properly format any logs you share.

Sum up your question in a clear title

Once you have a clear picture of the question, create or update the title to succinctly sum up your question. The title should be a relatively short summation of the question at hand.
The title is the first impression a reader will get and will often determine whether the reader will be interested or move on.

Create a minimal reproducible example

Including a minimal reproducible example often helps the reader to understand the question. Also, when the issue appears to be a bug, it helps the developers of Grav, or theme/plugin, to locate and solve the issue.

A reproducible example may be a complete GitHub repository, a gist, or even just a few lines of code.

Steps to create a reproducible example:

  • Use a fresh install using the latest version of Grav.
  • Use the default Quark theme, or mention the theme if issue is theme specific.
  • Only add extra plugins if required.
  • Using this basic setup, show step-by-step how someone can reproduce the issue.

Avoid using code screenshots

  • Screenshots are hard(er) to read, especially for visually impaired members.
  • Screenshots of code snippets, YAML etc, cannot be copied be the reader to try it out.

Share what you’ve already tried

List what you’ve actually tried already.

  • You don’t want to look lazy when asking a question.
  • Your last attempt may be one tiny step away from fixing the problem.
  • It prevents users from suggesting solutions you’ve already tried. Which is frustrating and a waste of time for both parties.

Format, lint and document your code snippets

Well formatted and documented code is so much easier to read. It also shows you care about the reader.

  • Add inline documentation to help the reader to understand the code.
  • In Markdown, code snippets like PHP, Javascript, YAML, JSON should be properly formatted and surrounded with tripple backticks (```). For example, use:
    ```
public function onPageInitialized(Event $event) {
  /** @var Page */
  $page = $event['page'];
  // etc.
}
```
    which will show as:
    public function onPageInitialized(Event $event) {
  /** @var Page */
  $page = $event['page'];
  // etc.
}

Keep track of your question

One of the most frustrating things for people answering questions online is the lack of feedback.

  • Don’t just ghost the people that are trying to help you. Provide feedback. Tell them what worked, what didn’t work, and why.
  • And remember, people aren’t paid for these services. They are paying with their time and effort to help you, so appreciate this and work with them to give them as much information as possible. It’ll pay off eventually.

Prevent cross-posting

Please don’t post your question in more than one forum (cross-posting). In each forum, people will be spending time and effort to answer the question and in the end, the time and effort in all but one will be wasted.

Instead, choose the best channel and wait a few days. Then post in another place. Provide links between each forum and repost the answer (link) in each location.

Other available channels

Apart from this forum, there are other channels you might want to try and which might be more appropriate before posting here.

  • Github - if your problem relates to a theme or plugin, this is the best place to start. Find its official code repository, and add an issue or discussion topic after searching.
  • Premium support: if you are paying for Grav Premium products, these include free support. Use it rather than asking volunteers.
  • If you prefer a real-time chat, there is a discord channel where problems can be solved. Discord is quite active and visited by the developer team.
  • Stack Overflow and its siblings: It is quiet on specific Grav questions but a huge knowledgebase on any other topic that is related to Grav (Apache, PHP, Twig, YAML, HTML, HTTP, SEO, etc.).
5 Likes