@jomaxro Your guide to polls on the Stoneheart Discourse is great:
I’ll link to it from my site for now, but it got me thinking. Is there any interest in collating good guides about less-used (or not so intuitive) Discourse features and packaging them on a GitHub pages site?
Discourse lacks good, coherent, up-to-date documentation. This would be a way to provide readable community-vetted guides to topics such as:
Creating polls
Changing email settings
Adding a site to the mobile app
Et cetera
I don’t have time to write all of these up, but I could write one or two and then rely on other admins to provide the rest.
Anyone else think this is a good idea?
(Unless something like this already exists and I just don’t know about it!)
Agreed - it would be good to have a standardised set of guides, and at different levels. Searching through meta for expert level stuff can also be hard
I’ve had to create my own (which has helped me to learn stuff and also to understand the user journeys) … so feel free to take a look:
Creating the content wasn’t all that time consuming, but after a year some of them need revising.
Our site was migrated from a platform which had remained unchanged for a long time, so there was a transition period while people found their way around. New users don’t seem to ask many questions (but few of them interact with Discobot).
After about 7 months the number of user questions fell off drastically, and the few that do get asked are usually fielded by other users (either as a reply to the question, or by pointing the asker to the #userguides category.)
What guides you need will, of course, be dependent on your user base. Our users don’t use many of the more advanced features, so what I’ve got seems to be enough. I don’t want to fill up the #userguides with so many howtos that users get discouraged. If someone asks a question that isn’t covered then I’ll create a new one.
We don’t have that many questions, either, but I imagine that the same ones come up at every Discourse (like the one about polls). I’m lazy, so I thought it would beneficial to pool resources
Edit: in the meantime, if other people want to post their local guides (as @robmc & @JagWaugh did), that would be helpful for others who are building their own. Merci!
I have mixed feelings about polls as an example, since 95% of it is “click the poll builder button and use the UI to build the poll”. You may recall that we added poll builder UI to address this a while ago.
I am very VERY anti speculative “hey someone, somewhere might want to know…” type of documentation. It’s a waste of time. However, if you can make a credible case that people are actually asking a certain “how do I…” question over and over, that is a valid case for doing this. But I need to see the data proving it, first.
But even better than documentation or guides, is to improve the UI / software so people don’t need to ask those questions in the first place.
In my experience, by far, learning Markdown syntax for code blocks is the single most requested How do I question. And this for a web dev forum where one would hope most members have some aptitude for things techy.
20 people searched for “avatar” presumably because they wanted to change an avatar, one person clicked through.
Making our search better here is our first priority, doing, here is a list of random guides cause we know you can not find them in search is kind of giving up imo.
Sure it might be worth pruning search results (READ: delete old obscure bugs and edit any noise topics that might interfere) for the top 10 search terms there.
That is why in the OP I specified “less-used (or not so intuitive) Discourse features”.
The poll builder is awesome. So awesome, in fact, that the “guide” to creating polls on my system is just 30 sec video of me using it to create a poll. That was mostly intended to show them where they can access it without resorting into potentially confusing verbiage (find the cog, etc.)
There are two issues with polls that, despite the builder, make them a bit tricky in practice.
After you create the poll, you can’t go back in the builder to make changes. So you have to understand what the structure of the “code” is. That’s why I linked to Joshua’s guide.
There are several “gotchas” with polls. Such as for example that you can’t change or delete polls after they’re created or that you can only have a maximum of 20 responses in any one poll [1]. I didn’t highlight these in the guide, but I’ve advised people about them in PMs.
The other two ideas I posted about also have tricky parts to them – at least they do in my case I’ll probably write my own guides to those parts I feel warrant the explanation. Not everything needs to be equally intuitive and it’s probably true that not all system share the same challenges.
[1] I’m not sure why that limit is there. If it is not possible to increase or remove the limit altogether, we could add some copy to that effect on the builder.
I’ll probably write my own guides to those parts I feel warrant the explanation. Not everything needs to be equally intuitive and it’s probably true that not all system share the same challenges.