How can I get users to read the docs/FAQ before asking new questions?

Question

I created an open source user management system for PHP which is (admittedly) directed towards novice programmers. The idea is to help familiarize "Cowboys from Code Canyon" with the tools and design techniques used by the professional PHP community, while providing a useful piece of software.

The problem is that my target audience also happens to be the same audience that has trouble reading/refuses to read documentation. I am starting to get burnt out from answering the same types of unresearched, quick-fix questions. Example questions include:

how can I render PHP file using Userfrosting?

how to do a new class public object visible to users and guest ?

could anybody point me to where i could read or find tutorials regarding Twig

These are all questions that could either be answered with a Google search, or they demonstrate a complete lack of understanding w.r.t. the basic software design concepts that I cover in the documentation.

I know I need to make the documentation a little bit more "in-your-face", perhaps with a few bold points in a popup dialog before they can download the software from the site. I could also put this information as a step in the installer.

But I really am skeptical that this will help, at least with the type of people whose first impulse when confronted with a problem is to ask someone else to solve it for them, rather than read the documentation and craft a specific, well-researched question.

Is there something I could be doing better, short of providing 24/7 customer support? Should I just put a big disclaimer in the README saying "I will not answer these types of questions"?

This may also be a good UX question, but it is "UX for an open source project".

Answer 1

Just to play devil's advocate:

One thing you may want to consider is that your current documentation might be suboptimal - no one may be reading your documentation because it isn't useful (to them).

• How easy is it to find your documentation in the first place?
• How easy is it to find a given topic within your documentation?
• Is there a clear path for a novice user to learn about your program?
• What's the learning curve like? Is there a good progression from complete newbie to experienced user, or do you go straight from trivial examples to a reference manual dump?
• Do you have multiple ways of finding information based on different mental models/outlook? (That is, things like tutorials, FAQs, demos, reference manuals - e.g. not everyone wants to puzzle out the answer to their question from a Backus–Naur grammer, even if it is technically the most accurate way of representing the information.)
• Why aren't people reading your documentation? And no, "because they're ungrateful, lazy schmucks" is not a sufficient answer, at least not if you want to get them to change their behavior.

Specifics:

Looking at you website, it looks like you could highlight "Documentation" more. On the main page, you have 'Download' 'Demo' and 'GitHub' as main buttons, but documentation gets a tiny text-only link. Documentation is at least as important to your users as a GitHub link - why not promote it?

In the upper right you do have a "Getting Started" link, but phrasing could be better. E.g. what will people who are thinking "I don't need to get started - I'm already using it; I just have a question about details" click? You have the "Help" button, but that's a bit confusing - is it "I would like to help this Open Source project"? "Help" in other sites also tends to be more "about this site/contact us" - to be honest, my eyes completely skipped over that link as useless boilerplate the first few times I saw it.

Even when you click on the "Getting Started" link, phrasing the links could be better. For example "navigating the code". I don't want to "navigate" Userfrosting, I want to "use" it. I guessing a fair number of users are skipping that page because they think it's an in-depth nitty-gritty code architecture page, rather than (apparently) your main documentation page.

The tutorials link is good ... but you only have the two. If you are getting repeated questions on the same topic, it's probably worth it to make some tutorials about that topic. This is especially true if you're targeting the novice user. You have to expect that they'll come in with little to none of the knowledge that you take for granted. There has to be an easy (for them) way of getting that knowledge, even if it's not directly related to your software.

Cross linking is also good. The "Components" link on "Getting Started" would be the spot to go to get an overview about the various parts of your program and how to use them, except that it has no links, making it hard to get more information about those parts. (E.g. if I wanted to know how to "Control privileges for users and groups", there's no indication of where I would go to find out.)

In the "Get Help" section on your main page, when I click on "Using Userfrosting", I get an interstitial pop up, and if I blindly click through (which, let's be honest, most people will do) I get dumped back to the front page. That is to say, the one link that - to me - would be the most important documentation link doesn't actually do anything. (Note that this is the same reason that popups on download or steps in the installer won't work - if the popups/steps are hoops to jump through rather than things which provide immediate benefits to the user, people will skip them.)

Finally, you have to think about searchability. Not just "how would I, as an experienced user, search for this information?" but "how would someone who has little to no clue about my software find this information, keeping in mind they might not know what the appropriate keywords are?" First off, your website has no search box available. If I want to search your documentation, I can't do it from your site, instead I have to go to an external search engine and be knowledgeable enough to know about the site restriction syntax, etc.

Even if I do a plain Google search, I'm not much better. For example, I typed "render PHP Userfrosting". Even without the site restrictions on search, I do get related pages, but nothing that a quick glance tells me anything related to rendering PHP (specifically). There might be synthesizable information in there somewhere, but I have ~2,000 Google results for this search, and others from the other search terms I try. Realistically, I'm giving each search result maybe 10 seconds before I give up and go onto the next one. Is there a specific paragraph in the documentation which specifically and directly answers this question? If so, why might I not be finding it?

I want to emphasize that last point. Roughly speaking, if you can't answer "unresearched, quick-fix questions" by a literal cut-and-paste of a single paragraph from the documentation, then either your documentation isn't comprehensive enough or the questions are more complex than you're giving them credit for.

Conclusion:

While it's true you will get a fraction of people who will never read your documentation no matter how easy it is to use, the threshold for "giving up" is a range. Each person has a varying level of hassle which they're willing to tolerate. It's not just those who immediately ask others for help and those who extensively scour the documentation to ask comprehensively researched questions. Depending on how hard you make it to use your documentation, you'll get more or fewer people who will make the attempt. Your goal is to lower the hassle level for using the documentation as far as you can.

Answer 2

There are a bunch of strategies that help you deal with beginner questions. Not all of them teach to RTFM, but you don't have to. Some strategies that can be very effective:

• Mobilize your userbase for support. Have a proper real-time communication platform (IRC, commonly on Freenode, and/or Gitter) to ask questions, as well as a mailing list. Users can help each other, and not all support has to rely on you.

• If a question has been asked many times before, and it's in the FAQ (you have a FAQ right?), you can simply answer with that it's in the FAQ, or that they can search the mailinglist archives (you have searchable mailinglist archives right?) for their problem.

• Have the API documented on your website. For many people, me included, on-line API documentation is by far the most useful form of documentation. Make sure it's good. Make sure it's complete. Make sure that if you notice many questions about a certain component, make sure you document that well on the API documentation. In order for your users to RTFM, you should have a FM. It lists it as "coming soon" already. You need it sooner rather than later.

• Have a search box right on your website that lets people find answer to their questions, if it's already documented. Making the FM easy to find and easy to search helps people to read it.

• You can offer paid support. Questions that bum you out are much more fun to answer if you get paid for that. An answer "you can search the mailinglist, or contact me directly to discuss the paid support options we have" is by all means reasonable. If they need a lot of hand-holding (and novices generally do), paid support might be the best route for them.

Answer 3

"Nobody" reads the f-ing manual.

But let me detail my answer a bit. It's statistics you see...

1. One only reads the manual when there is absolutely, positively nobody around that even remotely has knowledge on the subject matter. Anything, everything is better than the manual, because the manual doesn't contain THE answer to your question, it also contains answers to ALL other questions too.

Here you are, having only one tiny little question. Of course you might have another question right after this one, but this doesn't make it two questions, as the answer to the first hasn't been found yet. No need to read the manual.

Find the person who knows the answer! Find the person who knows the answer!

If you have another question repeat from 1.

2. One only reads the manual if you have all the questions at the same time, and in the right order. In this particular case the manual will seem magical in it's ability to not only answer each question you have BUT predict the next ones too. This is, statistically, almost impossible. No one has that many questions. No need to read the manual.

3. Find the person who knows the answer! You found him/her. Remember that statistically impossible task at point 2... well a knowledgeable enough person will be able to answer all your questions, in whatever succession and predict you future questions. Hurray, you've found a magical living manual. No need to read the manual.

Remember: Find the magical living manual who knows the answer!

NB. Are you a magical living manual? Hurray... now all you need is to ask money for your answers and you'll be consulting in no time. Ask for moderate sums, 1$ really easy, 3$ no time at all and 7$ for a good one. Start a spread sheet and keep tabs. When you hit 10$ ask for payment. Keep the sums small so that people find your services accessible, don't let tabs grow for new people, they might not pay up. For actual work done charge at 15 min intervals - 7$ this will get you decent rates and seem accessible (costs the same as a good question so if the question is hard you won't feel bad when it stretches, when 15 min pass and the question is too hard either ask for extension and more money or give up and charge 15 min instead of a failed good question)

Answer 4

As a project leader, for years I have tried to answer every single question coming to the mailing list of my user-oriented software, and I have found that:

• Many users can't read much English and don't have the skills to search/locate information efficiently
• Some users won't read the documentation even under torture
• Some users don't really trust the documentation or their interpretation of it, and will ask just to have a up-to-date confirmation by real humans

Your main goals should be:

• Don't burn-out. Keep enjoying the project, don't get upset to the point of getting angry, ignore questions that you don't want to answer.
• Delegate most of your tasks to other members of the community. Don't try to control everything.

Someone has helped a few other users? Give them some moderation rights on your forum. Giving rights to people make them feel part of the community, and encourages them to keep helping. Also give them write access to the documentation wiki.

Recently, a Reddit community has appeared and questions pop up on StackExchange, which I think is great: helping people where they are, questions are answered by the communities there (not always great answers but usually good enough).

Redirecting all support to StackOverflow (for a library/API) or SuperUser (for an app) or another more appropriate StackExchange site, or a dedicated subreddit, can be a solution but be sure to keep a venue for feedback which is not support questions, for instance an open bugs/enhancements tracker.

Answer 5

Apart from the earlier suggestion to make "Documentation" a very prominent link, perhaps the mechanism for asking questions should enforce the "search here first" paradigm.

Questions? Please type your question in the form of a Google query here :

<give some examples of queries>, e.g.
"Tutorials regarding Twig"

Then run the search on your site and see if it returns an answer. If it does, you're done; if it does not, you might have a genuine new question. If the short question passes the "no useful links found" screen, the user can then expand their question and it ends up in your inbox (or on a forum where others can contribute answers too - a bit like SE...)

Answer 6

First off, I will reiterate what others have said: "navigating" is not the verb I think to click on when looking for documentation. It sounds more like you're describing how to read the code that you wrote, compiled, and have posted a webpage about.

You have various things that fall under "documentation":

• White papers, general info, and misc guides
• How to use your software; tutorials
• API Documentation
• Legacy documentation

You should make some different categories and put your documents in them (some examples above). To explain those categories, you could have a list of the different types with pop-ups, mouse-overs, or some other UI widget to give a brief explanation of what's what. You could have this list under a heading of "help", "documentation", "wiki", or something similar. You could also/or have a Table of Contents, screencap depicting the navigation of your site, or something similar to catch people's attention and direct them to the right place.

I was not able to find any of your documentation until I read one of the answers here where they broke it down barney-style for you. Then I could find it.

Answer 7

The question has been around, but this is what I noticed based on the current situation:

• You mention often posed questions. If the same questions are posed more than once they will often at least contain some common keywords (or synonyms). A common search engine should be able to find hits in your documentation (or FAQ) based on the question, e.g. search for how can I render PHP file using Userfrosting
• If this works, is the page they found helpful for this question or is there an easy to find link to something which might answer the question? (My observation: it is not)
• You might want to do something for your SEO. My search above directs me to legacy.userfrosting.com. There is a banner on the top, directing me to the newer one, but doing this several times is simply annoying