We are excited to announce Bob’s Blog, a new column by Bob Ray, a truly amazing person, writer, teacher, and developer. I had the pleasure of helping Bob publish his first MODX book which still holds up today as the canonical reference on all-things-MODX so expect to learn helpful insights all year long (three articles per month). Occasional series will span 2-3 articles, but we’re aiming for mostly standalone topics covering various ways you can get more from MODX, the infinite configuration engine. Welcome aboard, Bob, and thanks for becoming an “official” MODXer. — Ryan, Co-founder, MODX
Bob’s Blog #1: How to Get Help
When you need help, you want it to be fast and accurate. This article is about making that more likely to happen.
I've written thousands of posts replying to people asking for help on the old MODX forum and the new MODX forum (I lost count at 23,000 posts). I thought I would give a little advice based on my experience. The examples are specific to MODX, but the advice applies to any situation where you’re asking for technical help on any Forum, in a support ticket, filing a bug, or anywhere else.
Let’s assume that your goal is to get a solution to your problem in the shortest possible time. A nice secondary goal is to maximize the efficiency of the people answering your question so they can answer more questions and get back to you faster the next time you need help. And let’s not forget the goal of helping other people who have the same or similar problems find the thread you’re starting. Let’s also assume that the average time it takes to get an answer is at least a few hours.
The Subject Line
Often, people are not sure what to put in the Subject line of a help request. Here's an example I've seen too many times to count:
At first blush, this might seem like a good idea. The Subject line begs for help and conveys the complete and utter desperation of someone who has been struggling with a problem and getting nowhere, so what's wrong with it?
Most people who help others on the Web specialize in certain kinds of questions. There are questions that are right in my wheelhouse. When I see those, I’ll dive right in and answer them. For some questions, though, there are other people who are better at answering them than I am. I leave those alone. I’m looking at several dozens of questions each day and I don't have a lot of time to devote to them, so I’m skimming the Subject lines looking for something that I'm sure I can answer. This subject line gives me no clue at all what the user's problem is. Unless I’ve got a lot of spare time on my hands (does any web professional these days?), I’m going to skip it.
Over time, helpers develop rules about what types of questions they will and won’t answer. For example, I almost never answer questions about e-commerce or server configuration. There are other people who are much better at answering those questions.
One common, unwritten rule among those who help is to not answer questions where the subject doesn’t tell you what the problem is. There are a couple of good reasons for this rule. First, a person who can’t or won’t tell you what they want to ask in the Subject line is likely to be frustrating to help in other ways.
The main reason, though, is that the answer may never be seen by anyone else because it has no information about the topic in the Subject line. As a helper in a forum, the last thing I want to do is answer a single question for a single user. The Subject line is not just for people who might help you. It’s also a signpost for other users with the same problem. Think about how a search engine will lead those users to your question based on the keywords in the subject.
Imagine that you want to check Google for an answer to a simple question. What are the odds that your search phrase is going to be just the word "help"? Write a Subject line that will be meaningful to helpers, other people looking for answers, and search engines.
The Question (aka the Problem Statement)
A good Subject line will get potential helpers in the door, but a bad question will drive them right back out again.
Questions, like the Subject line, need to provide information. Here’s a typical example of an inefficient exchange of information. Remember that there are often several hours, sometimes as much as a day, between each message.
Q: The Manager doesn't work.
A: Can you be more specific?
Q: I try to use the Manager, but can't save.
A: What Version of MODX?
Q: Revolution 2.2.7.
A: What can't you save?
Q: A Chunk.
A: What, exactly, happens when you try to save it?
Q: It doesn't save.
A: Yes, but what, exactly, do you see?
Q: It says "Saving" but it doesn't save.
A: Does this happen with all chunks?
Q: No, just one.
A: This is almost certainly a problem with
Let’s re-imagine that same conversation in a different form:
Q: There is one chunk that I can't save in the Manager. The "Saving" box never goes away and the chunk is not saved. MODX 2.2.7.
A: This is almost certainly a problem with
Notice that this didn’t require much more effort to write than the original question. The answer, though, comes back at least a day sooner. On some forums, the slower version above would take at least three days.
The bottom line for the body of your message is to provide enough detail for people to diagnose your problem. On the MODX Forum, we used to beg people to list their Operating System, PHP version, MySQL version, version of MODX, and Browser vendor and version.
Almost no one complied, so I’ll settle for this: Just be specific about telling me what, exactly, is happening. Phrases like “doesn’t work”, “fails”, and “messed up” tell me next to nothing in most cases.
If a user says, “Saving a Template Variable doesn’t work”, I can think of any number of reasons why this might happen and about as many questions: Does it happen for both new and existing TVs? Do you see an error message? Do you see an endless “Saving” alert? Is there anything in the Error Log? Does it happen with all TVs or just some? Does it happen with new TVs and/or existing ones? Do you have any permissions in place that might affect TVs? Is this a new installation where the problem has been there from the beginning? If the site was working before, what were you doing right before this started?
It makes me tired just thinking of all these questions and I might just move on to another question that's clearer rather than typing them all out.
After writing your question, and before posting it, pretend it’s by someone else that you’re trying to help. What more would you want to know in order to answer it?
Watch Your Pronoun References
I don’t want to go into the finer points of grammar, but there are certain words in a question that are likely to confuse the reader — the worst offenders are “it”, “that”, “this”, “those”, “they”, and “them”. Those words are fine when it’s completely obvious what they are referring to (like the ones in this sentence). At other times, they make your writing unclear, and you’re much less likely to get a good answer to an unclear question.
Consider the following question:
Q: I want users to be able to log in, edit a page, save the page, and then view the page in their user area, but when I try it, I get an "Access Denied" message.
There are four separate actions described in the question. Which one does the word “it” refer to? We have no idea. Look over your questions before posting them to see if they contain any ambiguous words. (“it” is the biggest culprit). If they do, replace the ambiguous word with the thing it is referring to.
The Five Ws
In Journalism school, reporters learn about the Five Ws: Who, What, When, Where, and Why. If you are asking for help, you are also being a reporter. You’re reporting a problem, and it’s good to keep the first four of these in mind. The fifth one, Why, is what you’re hoping someone will tell you.
You might think of skipping the first one, Who, because it’s obviously you. Sometimes that’s OK, but there are other times when it’s important to know who you are when the problem happens. Are you logged in as the admin Super User, a Content Editor, a sudo user? Are you a member who is not logged in? It can make a difference.
The other three questions are almost always critical if you want to get timely help.
What happens? Be specific and describe exactly what you see that isn’t what you were hoping to see. Screenshots are always welcome if it’s difficult to describe.
When does it happen? Does it happen every time or just some of the time. If it’s just some of the time, can you think of anything that’s different when it happens? What are you doing when it happens? What have you changed recently that might have caused the problem? If you upgraded, give both version numbers.
Where does it happen? Does it happen in the Manager, in the Front end, or both? Does it happen in the Create/Edit panel, in Quick Update, or both?
Make sure you’ve answered any of these basic questions that might be relevant to helping you find a solution to your problem.
Watch Your Tone
Everyone knows better than to ask a question like this (well, almost everyone):
Q: This CMS is a piece of crap. It won't even install correctly.
As you might guess, a person who posts this question isn't likely to get much help, but there are other subtler ways that your tone can affect whether you get help or not. This is made worse by the fact that you're probably tired and frustrated and perhaps hating the people who wrote the software and then hid critical pieces of the documentation from you.
Try to keep these facts in mind: People spent literally thousands of unpaid hours creating the software, you got for free, and now they're spending time that could be spent consulting for big bucks on helping you with your problem — for nothing. It's OK to sound frustrated, but try to sound at least a little thankful. Bear in mind that no one has to answer you. If your tone is hostile and insulting, I sure won't.
On some forums, it’s normal for people to insult one another and make new users feel stupid. The people most likely to do this, by the way, are people who were newbies themselves fairly recently and are insecure about their status in the community.
One of the things that first attracted me to MODX was that in the MODX community, personal attacks and condescension are not tolerated. Almost everyone is positive and people can disagree without insulting each other. Godwin’s Law, miraculously, does not apply in the MODX forum. People in the MODX community are almost always remarkably civil to one another.
Think about what kind of community you want to be part of and act accordingly.
One last tip about the tone of your question: Try to make the question about you, rather than the software. Instead of saying, “This doesn't work”, or “This is broken”, say “I can't get this to work”, or, “What am I doing wrong?” Not only will you be more likely to get a quick answer, you’ll save yourself embarrassment when the reply is something like, “Try spelling the word ‘Chunk’ correctly.”
When you see a person in a public forum who posts a lot and seems to know a lot, it’s tempting to send that user a PM asking for help. Don’t do it unless you are prepared to pay the person for their time, and even then, it’s often a mistake. There are several reasons why this is a bad idea.
Time is limited for helpers on a forum and the last thing they want to do is answer the same question over and over for each user who has the problem. They want to answer it once and let hundreds of users read the answer.
The odds are that you don’t really know what kinds of questions that person is good at answering. I often get questions in PMs that I have no idea how to answer.
When you ask a question in a PM, you’re betting that the person has the best possible answer for your question. The odds are against you. I lost count a long time ago of the number of questions I’ve answered in the Forum where another user posted a much better solution below mine.
Asking your question in public makes the Forum more efficient, is more likely to get you a quality answer, and saves the person you’re thinking of sending a PM to the time it takes to refuse to answer your question and tell you to post it in public.
Don’t worry about asking a stupid question. We were all newbies at some point and how I got to the point where I could write a book about MODX was by asking hundreds (maybe thousands) of questions that seemed stupid to me at the time. If you have a question, no matter how silly or unusual it seems, lots of other users have the same problem and will be glad you asked it.
It’s not unusual for me to spend an hour or more writing a reply and testing any code to make sure it's correct and does what it’s supposed to do. It’s frustrating, then, to never hear from the original poster again.
When you do get a solution to your problem, don’t forget to stop back and say so. Other users with the same problem will then know that the solution worked. It’s also good form to thank the people who tried to help you. Maybe their solutions didn't solve your problem, but they spent time and effort trying to help you out.
Mark the topic as “Solved” to help lead other users with the same problem to the solution, and keep helpers from having to wade through threads that are solved.
If you found another solution somewhere else, post it to help other users with the same problem. If you had to tweak the code someone gave you in order to make it do what you want, post your code.
OK, let’s summarize:
- Describe your problem in your Subject line
- Make your question clear and complete
- Watch your tone
- Avoid PMs
- Provide feedback
- Thank the people who tried to help you
- Mark the problem as "Solved"
This may sound like a lot of work, but after a little practice, you’ll be able to do it with very little effort. The payoff is that you'll often get help for your problem in a matter of hours instead of days.
Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.