## The Problem
Over the years, one of my biggest frustrations when working with Open Source projects, has been learning how to communicate (get help, suggest features, etc.) in each different community.
Every community has a different style of communication. Some simply use GitHub issues for everything. Others have multiple mailing lists, discussion forums, and IRC channels.
Quite often, I've posted a question and been told I posted it in the wrong location. Usually politely, but it always has a negative effect on my interactions with that community.
Then there's the "I'm developing this for free, you'd better make sure you don't waste my time on stupid questions." attitude. I fully understand not wanting to spend time answering questions that a simple Google search, or read through the manual, should answer. But, well, sometimes you can search and read for hours and still miss the answer.
I've done so many times. It's not pleasant getting a negative attitude after putting a lot of effort into avoiding "wasting" their time.
So, being a problem solver type, I really want to make communication better, for the user asking questions, the community member volunteering their time to help, and the developer spending his time building something awesome.
### Fix It in the Culture
Part of what needs to change is cultural. I'm not going to claim I have all the answers here, but I do have a few ideas on things that could help.
I believe that developers need to make a conscious choice that they will think the best of every interaction from the start.
Developers/community members should respond to every post by giving the poster the benefit of the doubt. Maybe the poster simply hasn't learned how to use Google well. (My Dad doesn't have very good search skills. He can spend hours searching for something I find in ten seconds.) Maybe they did search and didn't find the answer. Maybe they just didn't see the link to the docs. Developers/community members should take the time to couch their response in a positive manner.
(Note, I strongly believe that this good for both sides. Thinking positively is a healthy thing.)
Developers should also make sure how the community actually communicates is well documented.
Developers should set support expectations early. Make sure there's a prominent section in your README, or your sites front page, or somewhere, about what kind of support is available.
Projects and developers should make sure their communication channels are well documented. Especially on how each channel should be used, and what kind of response time can be expected.
If a developer doesn't have time to answer questions that are answered in the manual, say so in a prominent location. Then develop ways to easily communicate that the user should read the manual more thoroughly in a manner that doesn't make the user feel like an idiot.
Ultimately, users should feel welcome when they interact with a projects community.
Providing that kind of feeling takes effort. And it will lower development output. But a welcoming community should be worth that cost.
To end this section, I want to emphasize the importance of positive interactions.
One of the primary reasons I chose Ansible as my configuration management tool (for work and play), was that Michael DeHaan, the original creator of it, responded to questions personally. During my early learning curve, he responded to several of my questions in the Google Group. He never seemed dismissive or negative about any of the questions and feedback I saw him respond to.
The first pull request I created on GitHub was due to a couple of the members of the OwnCloud team providing positive feedback to my questions and suggestions. They actively encouraged me to contribute code that would fix the issue I saw.
More recently I've been very impressed with [Ryan Sipes](https://github.com/ryanleesipes), [Magnus Melin](https://github.com/mkmelin), [Andrei Hajdukewycz](https://github.com/Sancus), and [@wsmwk](https://github.com/wsmwk) (his full name isn't on his GitHub profile) from the Thunderbird project. They have provided very positive feedback to my questions, even the ones I expect might step on toes a bit. I've very much enjoyed [working](https://github.com/thundernest/thunderbird-website/issues/19) with them to [create](https://github.com/thundernest/thunderbird-website/pull/28) a Get Involved page on [Thunderbird.net](https://thunderbird.net).
On the other side of the coin, I've had several negative experiences with different projects. For most of them, I simply didn't bother with them anymore. Especially disappointing were the projects I was prepared to contribute code to if it would help.
So, seriously, a positive community is something to strive for! Even when it seems to add more work!
### Fix It in the Tooling
Fixing things by building tools is every developers goto method. I'm no different, and I think I've come up with some really good ideas. They're still in the idea stage, but if anyone knows of any projects like what I describe, or wants to start their own, I'd love to help.
The sheer number of tools (forums, IRC, Slack, GitHub, BitBucket, Bugzilla, GitLab, mailing Lists, news groups, Twitter, wiki's, doc sites, etc.) available, and in use, is astonishing. And extremely confusing.
So here's what I think we should aim for:
* When asking for help, it should NOT matter where you start to ask. Chat, forum, issue queue, anywhere, should be an appropriate place to start.
* It should be easy for content to be moved to the appropriate location in a manner that adds little work to the developer/modorator's workload, and helps the user learn where to go in the future.
* All the tools should start searching for the answer to the question as it is being typed. (Similar to what Discourse and Stack Overflow do, just more robust.)
When a user starts asking a question they should be presented with suggestions of searches to run, similar posts in the current channel, if it seems like it would fit in another channel better, etc. Ultimately, the user should be shown how to find the answers to their questions before they finish posting.
Users should be presented with appropriate templates to use when asking for help. Dynamically updating their post as they type with a better template could be interesting (or terrible.)
Every effort should be made to make it easy for a user to post the boilerplate information that is always asked for. A web app should have way for the user to output a sanitized report of their OS, system specs, and app config. A native app should have something similar, maybe as part of the about window. For bonus points, the output should be a full support request template, and users could hit a button and end up on a in their browser with the appropriate form already filled out.
On the developers side, the tools should make it quick to manage questions. If someone asks a support question in a bug report queue, we should be able to move that question into the support forum if it's actually a support request. If they ask a question in the wrong IRC channel, we should be able to move the question, and them, into the correct channel. If an IRC discussion runs out of time, we should be able to move that discussion into a support forum. Basically, we should be able to move any content, into any system.
All systems should have stock response generators for common issues. Developers/moderators should be able to hit a button, customize the output a bit, and the post it.
Forums should be able to act as mailing lists. That would allow those who prefer either method their choice.
In a nutshell, our tools should help users search for answers, help teach good communication habits, and help developers manage communication with little effort.
### Fix it by Standardizing Project Content Structure
(Any suggestions a better header for this???)
I've noticed that most projects need to be able to differentiate between several common kinds of content. When they reach a certain size, it becomes important that different tools be used for different kinds of content.
* Support requests
* Bug reports
* Feature requests
* User documentation
* Developer/Administrator documentation
* Tutorials
* Sub categories in all of the above.
* Etc.
A small project can deal with all of those kinds of content with just one or two tools. A GitHub/GitLab/etc. issue queue and a forum is often all that is needed.
Once they get larger, though, more is needed. And that is where things get confusing. Drupal, for example, has mailing lists, IRC channels, discussion forums, issue queues, and more. It took me a while to learn that the forums were largely useless, and that I should post in the issue queues if I wanted help. Of course, then I had to figure out which modules issue queue I should post in... Another example is Thunderbird. As I've been trying to contribute, I've found it very confusing. There's a MediaWiki, MDN, mailing lists, a Discourse forum, a couple other forums, something I think is a Question/Answer style system, and more.
So, here is an outline I think many projects could implement in a manner that would let users take the communication skills they've learned in one community, and apply them in a new one.
Of course some projects would not need some of these parts, and others may need more. But I think it is a good start.
Please do comment on this if you have something to say about it.
* **Main site**
* The **front** page should clearly describe what the project is.
* There should be a **Get Involved** page that clearly describes how people can contribute to the project.
* There should be a **Community** page that clearly describes each communication channel and how it should be used.
* There should be a **Documentation** page that leads to each kind of documentation.
* **Source Control Tool**: GitLab, GitHub, BitBucket, etc. Basically, code should be in version control, and the code should be browsable from a web browser.
* **Security Announcement mailing list**: Maybe as part of a discussion forum, but users need to be able to subscribe to email alerts about security issues.
* **Bug reports**: Likely as part of the source control tool, but it could also be separate. Developers should be able to set priorities, assign them to someone, etc.
* **Discussion Forums**: Every project should have a discussion forum available for users. It should have the following sections (as well as any project specific sections):
* **Security Announcements**
* **Release Announcements**
* **General Support (I need help but I don't know where to go)**
* **Documentation**: Should be considered authoritative. If something doesn't work the way the docs say it should, it's a bug. Docs should be created with a tool that allows easy community collaboration.
* **Question/Answer** style knowledge base: Something like Stack Overflow, but it could just be part of a discussion forum. Essentially, when there is a clear question, and a clear answer, there should be a way to link and display them together. Discourse seems to do a decent job at this, so something like that
* **Feature request** system: Users should be able to submit feature requests, and vote on the requests they think are important. Developers should have a way to clearly respond to each request.
* **Tutorials**: Possibly part of the documentation or just a forum. But there should be a way to vet each tutorial as accurate, mention what versions of the project it is for, etc.
I'm sure there are other parts we could add, and we might want to remove or consolidate some I have mentioned. But I think it's a good start.
Please do comment if you've read this far. I do really want to see these ideas go somewhere.
Thank you for reading!