I’ve been thinking about the best form of a FAQ quite a lot over the past months. I currently believe that the best way forward would be to move Discourse more towards being a one-stop shop whenever you need anything Stan, containing both discussions/help center and documentation/pointers to relevant, more detailed documentation.
Having some basic “howto” topics here on Discourse (e.g. “Introduction to divergences”, “Prior choice”, “Model selection”, “Using Stan Discourse effectively”) that would at least chart the landscape of other resources the user can use would have the advantages that
- Those topics could pop up in the “Your question is similar to”
- The users can immediately ask clarifications in the “howto” topics, so we get more feedback whether the instruction is useful and what is missing
- Once users studied documentation and failed to resolve their problem we want them to ask a question on Discourse. As they are already on reading docs on Discourse, this should lower the barrier.
- Making the post a wiki, all TL1 and above users on Discourse can directly contribute, in a format that they are already familiar with (this assumes everybody who has rights to edit GitHub wikis/push to main Stan site/… is on Discourse, which I think is true, while the converse is obviously not true)
- Generally, lower barrier for users outside the core contributors to make completely new “howto” topics themselves and have them easily discovered by the community.
- We don’t really have a single place to point people looking for “information to become better at Stan”. The forums are the least “movable” part of our information ecosystem - e.g. user-oriented GitHub wikis or directories of case studies on the main site can move to Discourse. Moving Discourse discussion to GitHub/main site is not possible.
- It is reasonably easy to get going and learn as we build it.
By the way we can customize the intro texts shown when people start composing their questions, so if we had good starting points for common problems (e.g. for divergences) we can link to them from there.
Storing docs along with discussions on Discourse is what http://meta.discourse.org does and it works quite good for them. The main disadvantage I see is that Discourse topics can become disorganized and disconnected in a way that a good old-school docs isn’t. When you know exactly what you need, it is sometimes hard to find it on Discourse Meta, even though it is there. On the other, accidentally discovering a piece of good info that you wouldn’t look for in the first place is - in my experience there - not uncommon. I don’t think we have the resources to really build and maintain another tome of knowledge on the scale of the Stan user’s manual, so less friction to create and discover the docs seems a good tradeoff for a bit lower usability for the user.
With that said, I am slightly skeptical a FAQ would, by itself, have a large impact on the number of inquiries on Discourse. In my view many questions that look almost identical to an experienced user, seem disconnected to a novice user. In other words, many users lack a lot of background knowledge that is necessary to make all the connections between their particular problem and the (often excellent) content already on Discourse. The bigger (and harder) task is IMHO to create resources to let users acquire this background knowledge more easily. Mike’s recent case studies are IMHO a very good step in this direction, although they are IMHO not suitable for all audiences. Our FAQs should definitely make it easier for users to discover those resources.
A good FAQ will help the forums and we should build one. If we do a good job, the FAQ could also be a good step towards resources that help users get the robust background knowledge they need.