(Mod edit: this was originally a PM but we agreed to make it public for wider discussion)
Hi All,
Didn’t get chance to speak to @gwmngilfen too much in Berlin (my fault) but one of the things that I found that made learning Ansible really hard was the lack of reliable help with questions, there are tons and tons of resources out there but a lot are outdated, and incorrect for the questions narrative, one I struggled with early on was down to something that worked in one version and not another (can’t recall what it was). Something that I think would help engage a lot more people would be a sort of quality guardian approach to answers, so that if a user asks a question they can be sure that they answer/approach thats suggested will work for them. I can appreciate how hard this can be in this sort of environment, both from a management and time management perspective to implement. It almost needs a “new user” section with a set of people that can either give specific answers, or verify that an answer is correct
One thing that I implemented many years ago in a company was when a user asked for help for something they would have to fill in a s template post, with information that was likely to variable, like OS version, management agent etc so that when someone else came to answer the ticket they could give an answer that was applicable to the versions in use
Templates are indeed possible, although in my experience with GitHub Issue templates they are frequently ignored. It’s definitely worth considering though.
yes of course, when ive used templates in the past ive always told people to google GiGo, then fill in the template, seems to prompt less technical people to give complete answers…
For 1 the answer is sort of. We can have a template that is inserted into each post - however you can only have one. Given the sheer breadth of information that might be relevant to different projects (e.g. compare an issue with a file-in-line playbook to a webhook error on AWX…) it seems difficult to design a useful template for all possible usecases that isn’t just really vague. However, I can see some scope for a very simple thing such as a reminder to include relevant information, etc. Thoughts here?
For 2, the answer is no, at least in the way I think you mean. This is the place for the community to support itself, and all are welcome to give input - indeed, that is the only way this can scale to the number of users Ansible has (as a FOSS project we don’t actually know that number, but my conservative estimate is “low millions”). Having a dedicated team will not scale, I don’t think.
Now, that said, the forum itself provides tools for this - over time. more people will hit that “Solved” button, and the people who are good at solving things will get recognised for it (check thesebadgesout. We can look to giving such people a prominent title (Support Expert, perhaps?) so that people can have confidence in their answers. Does that help address your concern?
I like the idea of a basic template in the help section. I think even a few vague hints can help.
As for a way to help new folks - I wonder if there’s a way we can help new ansible people help other…new ansible people? I tried this on another project and with a couple of mentors in the space, it really worked well. Tho it was for something far less technical than Ansible…
Or maybe we ask for a blog post or How To’ post here that is specifically directed to new Ansible users and gives them links to a curated list of resources that the community feels are accurate and helpful for onboarding new people into Ansible?
@gwmngilfen thats where I was heading in an indirect way a method so that if a user asks a question and gets 10 different replies, the ones that come from people who are verified/trusted, their answer can be thought of as true.
They are ignored at times, mostly by inexperienced users.
The follow-up - possibly automated - can be to ask the user to fill in the template, assign the issue to the user and set a label “waiting for user input” or similar.
Good idea. Automation is possible, of course, but not natively - I think we’d have to write a bot or something. However we do have template replies available to staff, so we can make it easy to reply manually.
There’s one other thing we can do, although I’ll have to test how it interacts with a “normal” template…
Using these docs it is possible to create a deeplink for creating a new issue with various fields filled in. That includes possibly filling in the body, for example:
Now we can’t easily make a whole bunch of these links here, but we can encourage the various projects to put this kind of thing in their docs (with a template they can then control, asking for the information they need). Not everyone will get here from there, but again it may help.
OK, so I think we need to get this going. How does the following template sound?
Please replace this text with a description of your issue. You should:
Include the version(s) of the relevant software tools, libraries, collections etc
Include relavant logs from the issue
Use backticks (```) to help format your logs and code (easy-to-read posts are easier to answer too!), like this:
- my code!
Set at least one tag (the experts follow the tags, so the right people will find you if you tag)
I’m deliberately not mentioning the over-use of Groups, and emphasising tag use instead - drawing attention to the possibility of mentioning a Group might actually increase the use of it. I think we should use replies like this when we see people abusing the feature
Sadly I think that’s a property of “relevant versions” because much of the time it won’t be - it might apply if, say, managing network config or SELinux, but not if interacting with switches or writing an API playbook.
At this point, how about start using the template, and see how it is used? The actual questions asked in the template can be slightly adjusted if it turns out that something is missing, or people misinterpret it, or add too many unnecessary details.
So @utoddl, @briantist@jrglynn2 and I were discussing this a bit in Matrix yesterday. If I recall correctly, there’s interest in knowing what (if any) research a user has already done, especially if that (a) helps them to find the docs, or (b) helps us to understand where the docs could be better.
a method so that if a user asks a question and gets 10 different replies, the ones that come from people who are verified/trusted, their answer can be thought of as true.
