27
votes
Ensuring users read documentation
There have been many, many, many threads over the past few weeks in which users (some new, some with a few posts under their belts) ask questions or make suggestions about items that are explicitly discussed in the documentation. Additionally, the documentation contains a lot of thoughtful items discussing the goals of the site and the mechanics for achieving those goals. The documentation is an integral part of this community, yet many people don't seem to be reading it.
How can the community help ensure that users read and understand the documentation prior to becoming a member of the community? A potential solution could be to have a short quiz based on the documentation, which would ensure that users at least skim it.
Any other ideas?
There's really no way to force people to read documentation. You can try, but most of the methods end up pretty intrusive or annoying, and bother everyone instead of only the people that they were targeted at.
I should probably just start removing posts (after linking to the docs) if they ask something that's directly answered by them, but sometimes it can be useful as a place for people to have a discussion about the topic even if it's already been covered somewhere.
I would caution against removing posts from new users unless they’re flagrantly inappropriate, especially at a time when we’re trying to encourage people to contribute.
I'm mostly talking about ones like this one (which I did remove): https://tildes.net/~tildes/22j/can_we_create_new_groups_subheadings
It's a yes/no question that's directly answered in the docs, and there's really no reason that it needs to be left active (where other people will probably reply and bump it up the listings repeatedly).
Well, there is one reason I can think of to leave those up; Because it increases the amount of new users that become aware of the answers to those repeat questions (and become aware of the documentation locations used in the answers) and so decreases the likelihood of it being asked again so soon.
If noise mitigation is your primary reason for wanting to remove them, you could always add a ~tildes.questions or ~tildes.help and maybe even a ~tildes.suggestions instead to contain them so people can unsubscribe if they have no interest in seeing them. Once tag filtering is enabled people can just filter those out even without a dedicated subgroup too. However those of us who don’t mind answering questions, even repeat ones, will still be able to see them and help people get acquainted with the site... Whereas if you simply remove them every time we can’t do that.
p.s. And once trusted user actions get implemented, being able to move and/or merge all repeats into a megathread style FAQ topic stickied to the top of the related subgroups would also help with that as well.
If other people are replying and discussing it, doesn't that mean it's worth discussing and/or new users are still learning about it? That has value to me.
...why not a quiz? Seriously, answer 3 questions and you're ready to comment. StackOverflow for example inserts test questions when a user is reviewing posts that have been closed. Why not some interactive way to test whether a person has read the docs?
It might be a reasonable idea, but it can be a bit difficult to figure out questions that work well. Do you have an example of the thing you're talking about on StackOverflow? I don't think I've ever seen that.
I think they're talking about review audits, which are posts that the system has decided are either obviously good or obviously bad, so it sneaks them into your review queue every so often to check that you're judging posts correctly.
They're not a perfect system, to say the least...
as ~anowlcalledjosh said, it's the review audits system. Something similar to that, but with 3 questions that are randomized from a pool of questions that touch on the various parts of the commenting policy. If you really want to comment, taking 1min to read the policy and 10 seconds to answer a 3 question quiz isn't much of a barrier.
Maybe allow the post to remain, but pin a link to the docs at the top of the comments? Maybe even linking directly to the part of the docs that addresses the question.
Include a link to the docs on the registration page, that way all new users can be made aware of it. The problem right now is that the docs are on the bottom of the page in tiny font, and most people don't notice it.
That and a link to them on the NewThread page - kinda like how github has a link to contributing guidelines when you try and make a PR (if the repo has them).
I worry that just having a link will not be much help — if a user is trying to complete an action (e.g. register or post a thread), they may be more likely to overlook elements that are extraneous to that goal, unless they are incentivized or forced.
I've read the majority of the docs published at https://docs.tildes.net and I still asked some questions that were answered there. I think there's a problem with the docs even when people read them. I'll quote an example from https://docs.tildes.net/overall-goals
The problem with this style of writing is that the reader has to discover what the main ideas are in a sea of long paragraphs, secondary ideas and filler words. The docs are long and tedious, and the main ideas are not highlighted for quickly identifying them. And when you reach the end you've already forgotten many of the important points.
I suggest making the main points of each section bold (or italicized, whatever looks better), like this:
You can’t and won’t, if your site wants to have broad appeal.
If you want to implement a post registration, pre posting test a user must undergo in order to limit your users to those who a) would read documentation, b) have read this sites documentation, and c) say they agree with the policies/goals/etc outlines in the documentation you total can, but...
Even with c, users who don’t actually care about aligning their behaviors with the documentation will agree to them and then ignore them. And you’ll push a great many people who either don’t read documentation or wouldn’t be bothered until they’ve participated a bit out of being interested in this site.
Agreed. I think a lot of early adopters on here forget that this site will never achieve a critical mass unless people are allowed to participate casually. Maybe it’ll always be a small forum if that’s what people want, but if not we’ll have to loosen up.
I think it could pay off to display the documentation/blog more prominently, rather than at the bottom where it's easily noticed. It might also be good to have a second faq giving short answers to these sorts of questions.
Case in point: I did not know the docs existed before seeing this thread
If we get the trust system implemented then highly trusted users should be allowed to remove those posts and send the OPs a link to the documentation.
I personally like the idea of "killing" a thread, where it will still be readable and found in "most recent posts", if that's toggled in someone's settings to show, but won't accept new comments, won't accept votes or show in any other views.
That would be fun actually. You can use NLP to dynamically generate questions.
Theoretically, yes, but I'm a bit skeptical about its implementation in practice. In particular, is it worth it to have (1) a stronger shared sense of the Tildes community philosophy and (2) fewer questions on features with readily accessible/discoverable documentation, at the cost of developing a meaningful quiz system (which will likely annoy new users with a good understanding of the community and features)?
Developing an NLP approach to generate quiz questions based on the documentation would be a nontrivial amount of effort (though not insurmountably so). However, I would be inclined to instead develop something like StackOverflow's suggested questions feature (i.e., when a user types a question, the subject/text can be used to suggest similar questions or sections in the documentation that likely contain the answer). This feature could be combined with @cfabbro's suggestion of a questions/suggestions group.
I don't know if they can be forced to read the docs, but perhaps a restriction on posting for new users might help. Let's say newly registered users can read the site but can't post for 48 hours. That way they can look around and hopefully pick up on the vibe here before they start firing off reposts and fluff threads. It seems like almost every problem thread so far has come from a user who is in their first day on the site.