FAQ tag vs documentation page

luceos

While running past all feedback from @Toby about the combined proposal for documentation restructuring, it seems there is no consensus about whether to have a FAQ tag or a documentation page.

We seem to agree that having both is too much, but what is the best solution?

Franz

To cite @Toby:

My feeling atm is that we should have it in the docs and discontinue the forum tag.

I disagree. If our FAQs are to become a living collection of frequently answered questions, maintaining them in the forum gives us a better chance of doing so. Maintaining a docs page that will have to be kept up-to-date with pull requests and so on introduces quite a bit of friction.

luceos

Franz I agree with you, but I wonder what the community thinks as well. Did they find it easier to search the forum (FAQ tag) or visit the docs FAQ page listed as menu item.

Would the FAQ tag become more effective if listed in the top menu instead of the docs version?

Dominion

Franz I disagree. If our FAQs are to become a living collection of frequently answered questions, maintaining them in the forum gives us a better chance of doing so. Maintaining a docs page that will have to be kept up-to-date with pull requests and so on introduces quite a bit of friction.

... And a fair amount of overhead, even if friction is avoided. That said, I tend to dislike the idea using forum threads directly as a FAQ because they tend to have a very low signal-to-noise ratio. When I look at a FAQ, I'd rather see just a question and an answer; any discussion that happens on the way to the answer (or after it) may occasionally be of use, but it most frequently proves to be a distraction.

But that's just my opinion. I'd love to hear what other users think about this.

Rodenastyle

@Franz @luceos Forgive me the intrusion on the Staff tag, but in my opinion expected information on the page FAQ is not the same as Documentation. FAQ means frequently asked questions, not all the people is looking for extending Flarum; people also could be looking for flarum system requirements and special features. So I also think that deal with both pages could be too much, but FAQ could be just few Docs-easy enhacements and about-flarum first time information.
PD: Job is done, it's just to get out FAQ from docs so people don't get afraid and make of Docs something like apidocs, what do you think? 😉

jordanjay29

Rodenastyle Forgive me the intrusion on the Staff tag

You haven't intruded, it was deliberately moved to a public tag for commentary like yours. 🙂

Rodenastyle

jordanjay29 Ups 😃 😃 😃

Kulga

Dominion forum threads directly as a FAQ because they tend to have a very low signal-to-noise ratio

Concur..
Currently, most tagged FAQ are guides atm anyways,

Rather, a FAQ would be better maintained in a single post in a Question \r Answer format.

For example, the What does Pusher do exactly? thread is a good question with a good answer
But there's a lot of extra posts in there..

Having a single discussions marked FAQ, updated from the posts creator and getting inputs from further posts would work well IMO.

In fact, this post (for extensions) follows this format perfectly.

Dakoom

You could create a "special view" for forum FAQs, if you decide to have them here on the forums. For example you could minimize the comments. Something like StackOverflow: example