Attribution: This article draws on and quotes extensively from the Chinese translation of How To Ask Questions The Smart Way, written by Eric S. Raymond and Rick Moen in 2001. Links to the original and the translation are at the end.
In running our technical community, we see all kinds of user questions every day, and we have found that many of them are not asked in a sound or efficient way. So we wrote this guide to asking questions for TDengine users, hoping to help everyone communicate more effectively. The methods and suggestions in this guide also apply to most technical communities and can help raise the overall quality of questions.
⏱ Before you ask
Before you ask a technical question in GitHub Issues, a technical chat group, or a technical forum, please do the following first:
- Try to find an answer by searching the archives of the forum where you plan to ask.
- Try to find an answer by searching the web.
- Try to find an answer by reading the official documentation.
- Try to find an answer by reading the FAQ in the official documentation.
- Try to find an answer by inspecting or experimenting on your own.
- Try to find an answer by asking a skilled friend nearby.
- If you are a programmer, try to find an answer by reading the source code at https://github.com/taosdata/TDengine.
When you ask your question, show that you have already made these efforts; this helps establish that you are not a lazy asker who wastes other people’s time. Even better, show what you learned along the way, because we are happier to answer people who show they can learn from the answers.
Prepare your question and think it through carefully, because hasty questions get hasty answers, or none at all. The more you show the effort you put into solving the problem before asking for help, the more likely you are to get substantive help.
Be careful not to ask the wrong question. If your question rests on a false assumption, people in the community will likely think stupid question… while replying with a pointless literal interpretation, hoping you will learn a lesson from the reply to your question rather than the answer you wanted.
Never assume you are entitled to an answer. You are not, you really are not. After all, you are not paying for this service. You will have to “earn” an answer by asking a substantial, interesting, thought-provoking question, one that can potentially contribute to the community’s experience, rather than just passively taking knowledge from others.
On the other hand, showing that you are willing to do something in the search for an answer is a very good start. “Could someone give me a hint?”, “What is missing from my example?”, and “Where should I check?” are more likely to get replies than “Please post the exact steps I need.” That is because you show that you have the ability and determination to finish the job once someone points you in the right direction.
📔 Try to find the answer directly in the documentation
In the “Before you ask” steps above, we already mentioned “Try to find an answer by reading the official documentation.” We raise it again here because the easiest way to learn a technology is usually to follow the official tutorial and use it to understand the product’s most basic technical concepts. For a deeper understanding, you need to keep studying the documentation.
Taking the TDengine documentation (http://docs.taosdata.com) as an example, a well-designed set of documentation usually contains the following parts:
Tutorials - learning-oriented
Help you quickly understand the product’s most basic usage in the simplest, clearest way. In the TDengine documentation, this corresponds to “Get Started.”
Explanations - understanding-oriented
Explain the product’s core technical ideas and architecture. In the TDengine documentation, this corresponds to “Data Model” and “Basic Concepts.”
How-to guides - problem-oriented
Describe specific features organized by functional topic. In the TDengine documentation, this corresponds to “Developer Guide,” “Cluster Management,” and “Operations Guide.”
Reference - information-oriented
An index of all syntax, functions, features, and technical points with detailed descriptions. In the TDengine documentation, this corresponds to “TAOS SQL” and “Reference.”
With these different kinds of documentation, you can find the different kinds of knowledge you need. For example:
- To understand the most basic time-series database concepts: see “Basic Concepts”
- To try out the database product: see “Get Started”
- To learn how to run continuous queries: see “Developer Guide - Continuous Query”
- To look up a configuration parameter: see “Reference - Configuration Parameters”
- To find an aggregate function: see “SQL Manual - SQL Functions”
And don’t forget that the documentation has a search feature; searching directly may be faster.
In this era of exploding technology, there are far too many technical concepts for anyone to remember everything. But the most basic requirement for a technical professional is to know the overall structure of the documentation, find the relevant chapter as quickly as possible, and then search within it.
🔍 Find answers by searching
Here are four search techniques for different situations:
Search the official documentation
The first method is to use the documentation’s built-in search. In most cases, you can find the knowledge you need through it.
Search within a specific page
On a page, use Ctrl+F on Windows or Cmd+F on macOS to search the page directly with the browser’s built-in feature.
Search Stack Overflow
Stack Overflow is the world’s largest community for technical questions. Most mainstream problems you encounter at work can be found on the site. In practice, most developers search through a search engine directly, and results from stackoverflow.com often appear among the first few.
The corresponding developer communities in China include SegmentFault, Juejin, CSDN, 51CTO, and Cnblogs. You can also find technical articles on professional technical content platforms such as InfoQ and general content platforms such as Zhihu and Jianshu.
Search with a search engine
A search engine is, of course, your ultimate weapon. As everyone knows, the friendliest search engine for technical people is Google, bar none. Compared with a certain mainstream Chinese search engine, you can find much higher-quality answers. When using a search engine, make good use of the site: operator to search a specific website. For example, to search the TDengine documentation, enter:
unable to resolve FQDN site:docs.taosdata.com
If the results contain a lot of noise, you can use “-” to exclude it, for example:
unable to resolve FQDN -DNS
In addition, China has a large number of high-quality personal technical blogs, and they carry relatively high weight in Google search.
🙋 When you ask
Identify yourself in technical chat groups
Even purely for commercial reasons, we are more interested in enterprise customers. Whether you are a free open-source user or an enterprise customer, identifying yourself may help spark our interest in your project and your question.
Mind your tone and attitude
In our long experience serving developers, we often run into situations like these:
-
What is this junk? Why is it so bad? Why has it caused me so much trouble?
-
Why hasn’t anyone answered yet? Where is everybody?
-
Where is XXX? Can someone tell me?
-
I’m in a hurry, someone answer right now!
Without a doubt, nobody welcomes questions like these. Engineers in the community have neither the responsibility nor the obligation to support you for free, and the officially run forums and WeChat groups are not places for you to vent. If you like TDengine, use it well, report problems carefully, and help build it. If you don’t like it, you can turn around and leave. If you haven’t made up your mind yet, you can keep following it or engage constructively with our team.
Groveling is not a substitute for doing your homework
Some people understand that they shouldn’t ask rudely or arrogantly and demand an answer, but they go to the other extreme and grovel: “I know I’m just a pathetic newbie, a total beginner, but…” This is distracting and useless, and it is especially annoying when paired with a vague description of the actual problem.
If you still don’t understand
If you don’t understand a reply, don’t immediately demand an explanation. Try to understand it first, just as you tried to solve the problem yourself before (using the manual, the FAQ, the web, and skilled people around you). If you really do need an explanation, make sure to show that you have already learned something from the reply.
For example, suppose I answer: “It looks like the zentry is stuck; you should clear it first.” Then this is a bad follow-up: “What is a zentry?” A good way to ask would be: “Oh~~~ I read the manual, but only the -z and -p options mention zentries, and neither clearly explains how to clear them. Did you mean one of those two? Or am I missing something?”
If you don’t get an answer
If you still don’t get an answer, please don’t assume we feel we cannot help you. Sometimes the people who see your question simply don’t know the answer. No response doesn’t mean you are being ignored, although admittedly the difference is hard to tell.
In general, simply repeating your question is a bad idea. It will be seen as pointless noise. Be patient: the people who know the answer may live in a different time zone, may be asleep, or your question may not have been well organized in the first place.
Questions you shouldn’t ask
Question: Is there an expert here who knows Grafana?
Answer: What is your question? Nobody will respond to this, because you haven’t asked anything specific.
Question: Is there a client driver for Mac?
Answer: Have you looked on the official product page, the download page, or the documentation? If you had, you would already have your answer.
Question: Creating a table reports System out of disk space. What’s going on?
Answer: The error message is perfectly clear.
Question: Has anyone run into Unable to resolve FQDN?
Answer: A quick search will solve it, and the answer is also in the documentation’s FAQ.
Question: May I ask, does a table not allow two records with the same timestamp?
Answer: That is a basic concept of time-series databases: timestamps are unique. Have you read the Basic Concepts section of the documentation?
Question: Teacher, do you have a TDengine-flink-mysql example?
Answer: Have you tried searching for “TDengine Flink MySQL”? If you had, you would have found the answer.
Question: The source code won’t compile. Why is it so bad?
Answer: He thinks it’s all someone else’s fault. This arrogant asker is not welcome.
🌟 Submit to GitHub Issues
Some issues are not consultation, Q&A, or discussion questions. They are usually very complex or are simply bugs in the code. Raising them requires clear context and a reproducible environment and steps, and resolving them requires in-depth technical discussion with developers. Such issues are not suitable for the community forum or chat groups; they should be submitted to GitHub Issues following the issue submission guidelines.
🧑💻 What is the TDengine team doing?
Nobody wants to answer the same repetitive questions every day or type the same things over and over, and neither do we. So we will keep doing the following to improve our work and steadily increase how efficiently we can help you solve problems:
- Keep expanding and improving the FAQ in our official documentation for common questions
- Publish the “TDengine Community Questions Biweekly Selection” every two weeks
- Keep iterating on the documentation, promptly fixing anything users report as vague or ambiguous
- Publish technical blog posts on various topics from time to time for questions in specific areas
- Improve the error messages output by the code, providing friendly and useful feedback wherever possible
- Keep improving code quality
We also hope you will join us:
- Report any documentation defects or typical problems you find at any time, driving improvements to the product and documentation and benefiting those who come after you
- Be bold in opening GitHub Issues; by opening an issue, you have already become a participant in an open-source project
- Be bold in submitting PRs, contributing code to the open-source project, getting involved, and becoming a contributor
💡 The difference between community support and enterprise support
Above, we have seriously discussed the techniques and taboos of community support. You now know that community supporters take on no obligations and make no promises to solve your problems. If you feel community support cannot meet your needs for timeliness, expertise, and deep customization, perhaps becoming a paying enterprise customer can help you quickly solve most of your problems; you will get dedicated resources and timely responses. But remember: whether you are a free user or a paying customer, as a high-quality asker, courtesy and respect are basic decency and ethics.
If you would like to learn how to become a paying enterprise customer, please leave a message directly in the community technical chat group, and someone from the TDengine team will contact you.
To join the community technical chat group, add the WeChat account tdengine or scan the QR code below:
Conclusion
The ultimate purpose of this guide is neither to lecture people nor to vent from a supporter’s point of view.
We hope this article helps developers find answers to their questions more efficiently and avoid wasting each other’s time on “beginner” questions.
This article draws on and quotes extensively from the Chinese translation of How To Ask Questions The Smart Way, available at: https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way/blob/main/README-zh_CN.md
The English original is How To Ask Questions The Smart Way, written by Eric S. Raymond and Rick Moen in 2001, available at: http://www.catb.org/~esr/faqs/smart-questions.html