With over 100 published videos, 60+ blog articles and dozens of Github repositories and Gists, I receive a lot of comments and questions. I try to respond to every legitimate comment received (but I simply ignore the trolls).
And helping others is the whole reason I started a YouTube channel and this blog. So I'm always more than happy to try to answer questions or assist someone with their project, Home Assistant automation or general DIY electronics. But I do get a bit frustrated when I receive posts like these couple of examples:
I could fill pages with comments similar to these. No details... no idea of what the problem may actually be. So to even begin attempting any assistance, I first have to spend time responding and trying to drag some details out of the individual that made the post. Often, this requires multiple exchanges just to get to the root of the issue before any progress can be made. This is often too time-consuming when I routinely receive multiple requests for help on a daily basis.
 |
| Based on original poster by Mr. Norcross - Kitley Intermediate School |
I initially saw the above printed as a poster and displayed in a 6th grade computer science class. I made a few tweaks to it for my own purposes, but it serves as a good example of "how" to ask for help.
Now, don't get me wrong. If you are reading this article, there is a good chance that you frequent some of the same Discord servers, forums or Github repos that I do. Some of these are a bit "over-the-top" (in my opinion) of what... and exactly how... you post an issue or question. Submit something that is incomplete or in the wrong "format" and you are ignored... or worse, ridiculed. I understand some of these projects deal with hundreds if not thousands of issues or questions and without some sort of standard format, it could be nearly impossible to manage. But this doesn't make it easy for a newcomer to post a simple question or to report their first issue.
And not every question or issue neatly fits into some of these templates. If you are newer to the subject, you may not even know how to obtain some of the requested information, such as logs or serial output. I'm not saying that to ask me (or many others) a question or raise an issue, that you must complete every question or field indicated below. But the more information you can provide upfront with your original question or issue, the quicker you are likely to receive a response and possibly even an answer or fix. While some follow-up questions may be needed, providing good initial information will help me (or others) to know where to begin looking.
Note: Any links to products in this article may be Amazon affiliate links. While it does not impact your pricing, as an affiliate this blog or related resources may earn a small commission if you make a purchase.
Information to Provide for the Best Assistance
Not every section listed below will apply a particular issue or question, but the more info you can provide, the better I (or others) will be able to assist you.
What task or project are you trying to complete?
Are you attempting to duplicate a project, automation or task that you've seen in a video, blog or elsewhere? Or are you creating a new project/task based on an original. What is your end goal or what are you trying to accomplish?
Examples:
Not-so-helpful:
- I want Home Assistant to turn on my lights.
- I want to use an ESP32
- My build doesn't work like yours
Beneficial:
- I'm trying to create an automation similar to your stair lighting, but to turn on the LEDs under my bed when someone gets up in the night.
- I'm trying to duplicate your Parking Assistant system, but with a system on each side of the garage.
- I'd like to build your matrix clock, but have the time displayed in binary.
What specific hardware are you using?
Not all hardware components are created equal! Just saying "ESP32" may not be enough. There are now multiple "models" of ESP32s. Add in hundreds of different vendors with various dev boards (and sometimes even different voltage regulators or USB-to-serial chips) and you have all sorts of potential issues. Specifying the exact model of components being used can help narrow down where an issue may be occurring. If the medium where you are posting your question permits, providing links to the actual parts you used can be helpful (some platforms may not allow embedded links). If you are attempting to duplicate a specific project or task, it is important to indicate if you used any different components from the original source.
Examples:
Not-so-helpful:
- I'm using an ESP32, potentiometer and microphone
- I bought my parts from "XXX" instead of "YYY", but they are the same as yours.
- I'm using a different sensor, but it worked fine with another project
Beneficial:
- I'm using a ESP32 Mini, 10K potentiometer and an INMP441 microphone
- I purchased all my parts from Aliexpress. I think they are the same parts, but here are the actual part numbers:....
- I'm attempting to use an HC-SR04 sensor instead of the VL53L0X ToF sensor. I know the sensor is good because I used it in another project.
What version(s) of firmware, software or utilities are you using?
Similar to hardware, different versions of firmware or software can introduce unexpected results. If you are a Home Assistant or ESPHome user, you likely know that each month brings a new release... often with breaking changes and multiple follow-up patch releases. If your project uses any firmware, software and/or utilities, you should indicated the version(s) used. As an example, installing custom Arduino firmware for an ESP32 could involve all of the following versions depending on how you are installing:
- Arduino IDE version
- ESP board manager (core) version
- Flashing utility (e.g. NodeMCU Pyflasher, ESPHome Flasher, etc.)
- Firmware libraries used in the Arduino code
- The compiled firmware version itself
Examples:
Not-so-helpful:
- I installed WLED (or Tasmota or ESPHome code)
- I downloaded and installed your code from Github
- The code wouldn't upload
- I installed WLED 0.14.4 audio-reactive version using the WLED web installer
- I downloaded the v0.44 .bin file from your repository and flashed it using NodeMCU PyFlasher v5.0.0.
- I tried to flash the 0.44 .bin file using ESPHome Flasher v1.4.0 but it won't connect to my ESP32 Mini. It show Connecting... but eventually times out and the code never uploads.
What specifically are you seeing (or not seeing) vs. what you expect?
Describe exactly what you are seeing vs. what you expect. What you don't see can be just as beneficial as what you do see. Even if the project (or automation) doesn't include any sort of visual display, there may be other indicators built into the firmware (such as the LEDs on an ESP board, startup MQTT message, etc.) that indicate a normal boot process or operation and can be used to potentially indicate a particular problem. Check the firmware or source documentation to see if any system indicators are available.
Not-so-helpful:
- Nothing happens
- No LEDs come on
- It doesn't work and I don't get any values
Beneficial:
- After powering on the ESP32 via USB, the red LED turns on but the blue LED never blinks like the documentation says it should.
- The system powers on and completes the boot sequence, but only the first 30 LEDs come on in orange and I cannot change colors from the web app.
- My sensor entities appear in Home Assistant, but the developer tools always show 'unavailable' for the state.
Do you see any sort of error message displayed or other error indicators?
If the system outputs any kind of information or if you can access any log files (if they exist), including this information can be a great help in diagnosing the issue. Even the lack of output when something is expected can be beneficial. Note that log files can often be lengthy and some platforms or forums may not permit postings of this length. See the section below on posting code and logs.
But this is similar to the above "what do you see". Try to carefully observe the system (assuming there is anything to watch) and note anything that occurs that isn't what you expect or the documentation states that you should (or shouldn't) see. If your device or project is integrated into Home Assistant, what state do the entities show in the Developer Tools?
What troubleshooting steps have you tried and what were the results?
If you have tried any basic troubleshooting (and you should at least try some basic steps before asking for someone else's time to help), include what you tried and what results you received. Common steps will vary based on the project or task, but some common troubleshooting steps might include:
Projects and Builds
- Verify power source and that the system is receiving the proper voltage and that the power supply can provide adequate current (amps).
- Check all wiring and soldering connections (if applicable). It is a very common mistake to reverse connections on things like RX/TX or the data/clock lines on some components.
- Have you tried replacing any of the components? If possible, swapping out each component (including the ESP board, any sensors, etc.) can determine if the issue might be related to a faulty or incompatible component. It is not uncommon to receive an occasional faulty device (or batch of devices) due to the low cost/high volume for may of these electronic components.
Coding and Automations
- Your code IDE or editor will often include syntax, compile or other messages (these can sometimes be found in log or serial output). Include the message and the line or section of code that appears to be generating the error.
- For things like Home Assistant automations that may have been created via the UI editor, you can still look at things like the state or state changes of entities via the developer tools, review the automation traces, etc.
Your troubleshooting steps can not only provide valuable information, but also let's the individual you are asking for help know that you've at least tried to resolve the problem yourself before asking others for help.
Have you reviewed the documentation/wiki/blog/video for the project?
If the project or automation you are trying to replicate or adapt has a related video, blog article, Github repo (maybe with a wiki) or other information, you should review the documentation. You may have skipped or missed an important step or requirement. I've had many situations where someone reports back "Oh... I missed that in the video/blog!"
In addition, most of these media sources have a comment, issue, discussion or feedback section. You may wish to at least scan or search these sources. It is possible someone has experienced the same issue as you and a solution may already be posted in response. It can be frustrating to help someone asking a question that has already been answered (often multiple times) because they posted a comment but didn't bother to read other comments already posted that contain the exact answer to their question.
Posting Code, Logs and Links
Posting your code (or things like your YAML automation) or log files can be problematic in many discussion or forum areas as they may both limit the size of the posting and also may not have a way to maintain proper formatting/layout (which can be critical with something like YAML).
First, check the options and limitations of the comment section/forum you are using. Some may provide a way to format a 'code block' and maintain the layout. For example, when posting in Discord or Github (markdown), you can create a 'code block' by surrounding your code with three 'back-ticks' - the symbol under the tilde (~) on most US keyboards. Others may offer a formatting button or other option for posting code or text while maintaining the layout. You can see the difference here:
Posted as plain text:
automation:
- alias: Top Motion Lights Off
trigger:
platform: state
entity_id: binary_sensor.stair_motion_top
to: "on"
for:
milliseconds: 250
condition:
- condition: state
entity_id: light.stair_lights
state: "on"
- condition: state
entity_id: input_boolean.stair_auto_leds
state: "on"
action:
- service: light.turn_off
entity_id: light.stair_lights
Posted as a code block:
automation:
- alias: Top Motion Lights Off
trigger:
platform: state
entity_id: binary_sensor.stair_motion_top
to: "on"
for:
milliseconds: 250
condition:
- condition: state
entity_id: light.stair_lights
state: "on"
- condition: state
entity_id: input_boolean.stair_auto_leds
state: "on"
action:
- service: light.turn_off
entity_id: light.stair_lights
As you can see, posting as a formatted code block not only makes it much more readable, but can also help identify where there may be an issue with something like indentation... which is impossible in the plain-text version.
But what if the platform you are using does not provide code block formatting, or your code/logs are still too long? Well, you can use one of the many free services out there, like Pastebin or Github Gists to post your code or logs and then provide a link in your comment or post. If the platform doesn't allow links (many may allow them but the message is held in a moderation queue until approved), then you just need to modify the link so that it makes sense to the reader.
For example, instead of: https://pastebin.com/MRj7xT9s
Modify the posting to read: pastebin-dot-com/MRj7xT9s
Any other information that you believe might be helpful
If the medium you are using permits, include any other meaningful information that you think might be helpful. This could include photos, video clips, diagrams or anything else you believe might be beneficial. From someone that answers a lot of questions, I'd rather have too much information than not enough. Not having all important information can slow down the resolution process (because of the back and forth needed to get this info) or even lead down the wrong path... wasting more time. If you think it is relevant, include it!
Where to Start and What to Watch Out For
If you are newer to a topic, you may not even know where to start. This will vary widely depending upon the source(s) you are using, the topic/type of question and even based on the creator himself/herself, but here are some general recommendations as to where to start.
If you are trying to duplicate or adapt a project you've seen in a YouTube video or blog posting, you may want to consider posting a comment/question in the comment section of those platforms. Some creators monitor and reply to comments on their content. Others may not. You can normally take a quick look at existing comments and see if the author is responding. But this is normally a good place to start and there may be other members of the community that can help even if the original author doesn't respond.
But what if there isn't a comment section or you can't find any help there? Here are a few other sources to try (but see the rest of this section before "blindly" posting):
- Discord
- Facebook Groups
- Github (for projects with code repos)
- Forums and bulletin boards
But before posting for your first time, here are some additional tips to consider:
Always start with a search
Before posting, you should utilize the platform's search feature (if it has one) to search for your issue or question. There's a good possibility that someone else may have experienced your same problem and a solution may already be posted. You do run the risk of rubbing some authors/communities the wrong way by asking a beginner's question that had already been asked and answered (and maybe even multiple times). Why? Well, it shows that you haven't spent any time trying to solve the problem yourself and are just blindly asking someone else to give up their time to help.
Often you can just search via Google and will often find a solution or at least very similar problems. If you have an error message, you can often paste the error message directly into Google's search bar and may find an answer.
Browse the platform before creating your first post
Every community has its own "culture and feel". Some, unfortunately, are less welcoming to beginner questions than others. Browsing a few posts and their responses will help you get a feel for how others are asking questions and how the community is responding.
Pick the appropriate topic or category, if it exists
If the platform offers categories, topics or threads, try to pick an appropriate one for your initial question. You likely won't start off on the right foot if you post a question about golf in a topic on baseball. This might not seem like a huge deal to you, but some large communities may have teams of volunteers with various specialties that monitor particular topics or categories and they are dealing with literally hundreds of posts each day. In addition, posting to the proper category can also help others who have the same problem later find a resolution (because they searched before posting!).
Not every forum will have categories or you may not find a matching topic. If so (and you either don't or can't create a new one), look for a 'General' category or similar and start there. Some communities are more "sensitive" to proper use of topics than others. But don't just blindly cross-post in multiple categories. This will likely irritate others... and could even get you banned. Which brings up another important tip.
Look for any 'rules' or 'requirements'
Some platforms may publish 'rules' or recommendations for posting. This is more prevalent on platforms like Discord or maybe Github. For example, many Github repos may not want to use the issue tracker for answering how-to questions or installation problems. Instead, the issues section is used for reporting suspected bugs with the firmware and a discussion area is used for general questions, enhancement requests, etc. Always look to see if any published rules or processes and follow them if possible. You are unlikely to get help and blindly make your first post in direct violation of the recommended method. Again, this shows a lack of effort of your part.. yet with the expectation that someone else will invest his/her time to help you out.
If one source doesn't work, try another
Some platforms are more encouraging of beginners than others. It's unfortunate, but there are some (I'm thinking specifically about certain Discord servers and subreddits) where it is more of a "good 'ol boys club" and if you aren't an insider, it's like walking into a Harley bar wearing a Kawasaki t-shirt! Yeah... you might find help, but it probably isn't the best place to ask about Kawasaki motorcycles!
So don't hesitate to locate a different platform if you aren't able to receive help from one.
Corroborate any questionable replies
Yes... this is the Internet. While most folks that volunteer their time to help truly have good intentions, it doesn't mean that you might receive bad... or even dangerous... advice. If something doesn't seem right or your don't understand a response, then try to either follow up for clarification or consider taking the original issue and response to a different platform and asking someone to verify.
Don't get discouraged!
If you are just starting out, don't get discouraged if you question isn't immediately answered, or worse you get a snarky or non-helpful response because you didn't follow some arbitrary set of rules in a particular forum or server. This will happen! Just try a different platform, forum or server. For every jerk you run into, there are probably at least a dozen others that would be happy to try to help you out, myself included.
Eventually you will find a good medium or platform where beginner questions are answered without patronizing or ridiculing those asking the questions. But learning how to ask that question (and eventually the behavior or 'etiquette' of a platform) will make asking for help in the future much easier... just don't let an idiot or narcissist discourage you from learning!
Follow up with the solution
Once you resolve your problem, don't forget to follow up and post the solution or at least mark a response as the answer to your question. This can greatly help others that may later run into the same issue and are also looking for a solution. Recall above that one of the steps above was to look at existing comments or posting to see if your problem has already been addressed. Be sure that you give back by letting others know what your solution was. Posting a solution, or at least a message that your issue has been resolved, let's other individuals that might have been assisting know that a fix has been found so they no longer need to spend additional time researching the issue.
In addition, please remember to thank those individuals that may have offered you helpful assistance. Many of us do this strictly on a volunteer basis and may spend hours trying to help someone else solve an issue... even if it wasn't initially their own project. While absolutely not necessary, if someone spent a significant amount of time and effort helping resolve your issue, you can also consider expressing your thanks in a more 'tangible' way. Many creators have Paypal, Buy Me a Coffee or other sources where you can optionally say thanks with a few dollars. But for many creators, there are often many other 'non-monetary' ways to offer thanks and support. Some options might include:
- Subscribing or following on YouTube or other sites.
- Using affiliate links. If you need to purchase parts and the creator offers links (Amazon is the most common), using one of these links to navigate to Amazon and then making your purchase will earn the creator a small commission, while not impacting your cost at all!
Build Up Your Support Network
If you post good starting questions and remember to thank those that helped, over time you will begin to establish a network of individuals that you can turn to for additional help in the future. Maybe you have a couple of individuals that are good at small electronics, a few others that are knowledgeable with Home Assistant, etc. Just remember that most of these individuals volunteer their time and may have their own full time jobs, personal projects, etc. So do try to be cognizant of the time you may be asking others to give up to help.
Overall, I've found that if you can frame your initial issue properly, ask in the proper location (e.g. don't post an electronics question in a forum about woodworking), you will find individuals that are willing to help you out.
Learning how to ask for help can often be as much of a learning experience as the project itself! But if you try to follow the simple advice above, always show gratitude for any assistance you receive and stick with it, you will almost always find someone that is willing to help you out with your project!
Best of luck with your future projects. And remember... there are plenty of us out here willing to help. You just have to ask!
Supporting this blog and related YouTube channel
It takes significant time and effort (and occasionally expense) to create these articles and videos. If you'd like to support future content on this blog and the related YouTube channel, or just say thanks for something that helped you out, you can consider buying me a one-off cup of coffee or two at:
No comments:
Post a Comment
To help eliminate spam and to keep all conversations civil, submitted comments are moderated. Therefore your post may not show up immediately. Please be patient as most reviews are completed within a few hours.