Ideas for community building at the GitLab Discourse forum
Overview
Story
Why
This originates from a discussion on EE and CE, and general community building on the forums. https://forum.gitlab.com/t/is-this-product-open-source-no-charge-i-host-from-home/32225
I've discussed many things written here already with @LindsayOlson and @greg :)
Also, I've been digging quite extensively into the community channels and have taken notes on improvements, and how I can be part of it. That's one of my self-granted tasks to learn more about the product, the project and how users and customers see it. @pritianka @nwoods1 @melsmo know about this effort.
With all the ideas proposed below, if there is an agreement, I'd like to offer to implement these changes into Discourse e.g. together in a Zoom session with granting me admin permissions and we'll learn from each other.
Once there are specific tasks, we should create sub issues or an epic tracking this.
Background
Building open source communities isn't something where a guide exists, you always try things and see whether they work how you intended them. First things first, a forum generally solves one purpose: Asking a question about a feature, a problem, something else and others chime into the discussion. The technical platform should be appealing, easy to use, and allow developers, contributors, users and customers join together.
I've built community forums with phpbb3, Woltlab and most recently Discourse in the past 15 years. The hardest thing to achieve is to make people stay after they have gotten their answer for their question. Be it with gamification, a gentle "Hi, thanks, regards" culture or the possibility to learn more from browsing existing topics. Also, appreciating everyone's work for the fun and pride with additional thanks is important.
Nowadays every project or vendor has its own community where the experts write and discuss. Combined platforms with generic topics don't really work.
With GitLab, it wasn't clear to me whether the Discourse forum is now run by community members, or managed by the GitLab team. Also, since a lot of discussion is going on in issues on gitlab.com already.
Since the issue tracker solely is for possible bugs, feature requests and release management, the forum adds a layer up front: Figure out configuration problems, troubleshoot performance problems, and decide upon creating an issue at the point when there really is a bug or missing feature.
Yet, community members wish to see more activity by the GitLab team being part of the wider community too. Recently more community advocates joined and now it is our mission to make the forums a welcoming and engaging platform fully integrated into gitlab.com
My ideas range from creating better topic content, allowing supporters to focus to more gamification and even marketing and social media benefits. Many things of the below are actively done in the Icinga community and have evolved over the last 10 years.
Also, Discourse inspires me every day - for example, to solve the spam problem on gitlab.com: gitlab-org/gitlab#14156 (comment 258252735)
Ideas
Forum Introduction
Make it clear that this forum is an official community channel.
Discourse doesn't explain everything, and not so many people use the interactive learning mechanism with the discobot. Therefore the basic things should be covered within extra topics which can then be linked from specific pages (FAQ, banners, etc.)
- Registration and Login, explaining the social logins with GitLab. Same as https://community.icinga.com/t/registration-and-login/187
- Create topics and master markdown formatting, same as https://community.icinga.com/t/create-topics-and-master-markdown-formatting/69 (especially formatting configs, logs, etc. with indent or 3 backticks is hard to learn)
- Mark a topic as solved - rationale how this works and why one should do that https://community.icinga.com/t/mark-a-topic-as-solved/70
- Explore Discourse with discobot - just to remind users to go there, and also earn a badge https://community.icinga.com/t/getting-started-explore-discourse-with-discobot/71
Banner
When you visit https://community.icinga.com/ you'll recognize the blue banner on top. This summarizes the most important topics to start with.
This actually is the default welcome to discourse topic changed into a global banner, filled with helpful details. https://community.icinga.com/t/welcome-to-discourse/7
The GitLab Community Forum is a great place to discuss GitLab, CI/CD, integrations, ideas and help resolve possible problems together. Stay a little longer and join our lovely community sharing the #gitlablove :heart:
## Registration and Login
You can either register a local account or use a social login. [Read more](<!-- TODO: Topic -->).
## FAQ & Code of Conduct
Please read and follow the FAQ and Code of Conduct carefully. [Read more](/faq).
## Learn more about Discourse
We have added important topics, howtos and insights already to get discussions started more easily. Navigate into the different categories and learn more :tada:
In addition, peak into the following topics:
* [Explore Discourse with Discobot](<!-- TODO: Topic -->)
* [Create topics and master Markdown formatting](<!-- TODO: Topic -->)
* [Mark a topic as solved](<!-- TODO: Topic -->)
How to ask a question
From the FAQ, it is not clear how to really ask a question. In the past months, I've been reading through the archive and the quality of question differs. Either there is a sentence containing one question where you'd need to ask again for more details on the environment, or the topic already contains valuable details.
The key elements are:
- Motivate users to take the time to write thoughtful topics with their questions
- Be a role model and encourage with replies to follow the FAQ where this is explained. The next question/topic hopefully learns from that.
Ideas to solve this:
Topic Templates from Discourse
Simple, short but with providing enough details. Do not use the GitLab Bug/Feature templates, they are too long and complicated for the initial kickoff for a question.
# Describe the problem
<!--
Which problem did you encounter
-->
# Things already tried
<!--
Documentation and howto URLs,
-->
# Context
<!--
Add as many details as possible to help others understand your situation.
Screenshots, config snippets, log output, etc.
-->
# Versions
- GitLab versions:
- Self-hosted ( e.g. `grep gitlab /opt/gitlab/version-manifest.txt`):
- Web (`https://gitlab.yourdomain/help`):
Extend the FAQ
Within the Icinga Community Forums, the Discourse platform mostly is used for Q&A. Therefore I've extended the FAQ in a way that you'll get to know everything before asking a question. This sources from years of community support, including troubleshooting and docs references.
https://community.icinga.com/faq#qa
Everyone asking a question should:
- Understand how to describe a problem
- Why to use images or screenshots to illustrate the problem
- How to extract versions from the GitLab environment
- How to grep in configs, format logs, etc.
- Where are the common locations for logs, configs, etc
- Learn how to troubleshoot their systems
People helping out should just be able to point users to one location to provide more details, e.g. with using quick typed relative URLs.
You can find more details in the [FAQ](/faq).
Good example for listing possible parts: https://forum.gitlab.com/t/gitlab-self-hosted-license-page-missing/32003/5
Consider adding the following sections, adopted for GitLab:
Intro and TOC
This platform is made with love for community discussions on GitLab, CI/CD, integrations and anything related to the #devops :heart: culture.
1. [Questions and Answers](#qa)
1.1 [Before you ask your question](#before-ask)
1.2 [Format topics with Markdown](#format-markdown)
1.3 [Details you should always include](#details)
1.4 [Steps to reproduce or understand the question](#reproduce)
1.5 [Add the things you've tried already](#tried-already)
1.6 [Pick a solution](#solution)
Content
<a name="qa"></a>
# Questions and Answers
<a name="before-ask"></a>
## [Before you ask your question](#before-ask)
* Use your preferred search engine such as [Google](https://www.google.com) and the **[search](/search)** here. Maybe a similar topic already covers your problem.
* Does the documentation provide a **troubleshooting guide** already? Try that first and add your findings here. Example: [Troubleshooting Wiki Guide](/t/troubleshooting-guide-wiki/31)
* If you think you've hit a bug, look into the upstream **GitLab** project if it already exists and link it in your post. Example: https://gitlab.com/gitlab-org/gitlab/issues https://gitlab.com/gitlab-org/gitlab-runner/issues
Please make sure to **include every little detail in your question**. This helps community members to analyze your problem. They do not need to ask again to find out more about your issue.
Sometimes a screenshot or a handcrafted overview picture help even more to understand what you mean.
<a name="format-markdown"></a>
## [Format topics with Markdown](#format-markdown)
Please format configuration snippets, source code, logs, shell output with Markdown (three backticks or 4 space indent). This makes your questions far more readable and others can identify things faster.
> More tips on Markdown and general writing can be found in [this guide](<!-- create and link markdown guide -->).
<a name="details"></a>
## [Details you should always include](#details)
* Which documentation source did you use (URL, short quote).
* Distribution name and its version (`/etc/os-release` or `/etc/*-release` or `/etc/*-version`) in case of self-hosting GitLab.
* Software versions (`https://<gitlabserver>/help`).
* Installation method (Omnibus packages, self-hosted or SaaS on gitlab.com).
<a name="reproduce"></a>
## [Steps to reproduce or understand the question](#reproduce)
* Configuration files you've edited - their content formatted with code tags, their location on disk.
* CI/CD setup with GitLab runners, if important.
* Order of things, e.g. CI job was triggered, corresponding log entries, your analysis.
* Which steps are needed to reproduce the problem isolated in a local environment or at gitlab.com?
> **Tip**
>
> Keep your private details safe. Remove passwords, credentials, etc. and obfuscate host names from your company environment.
<a name="tried-already"></a>
## [Add the things you've tried already](#tried-already)
* Configuration changes which did not work - they help explain your idea.
* Docs and howto URLs you've found, maybe they do not match 100%.
* If it could be a bug, did you try a snapshot package or attempted to fix it already?
> **Tip**
>
> Do your homework and describe your thoughts in detail. Don't throw something short and ask for a ready-to-use solution.
<a name="solution"></a>
## [Pick a solution](#solution)
If your topic was answered with a helpful solution, make it visible for others and mark it as **solved**. Each reply has this icon (see below) and rewards the author with a [badge](/badges). Do not edit the topic title no more, and have a fancy icon in listing and search results too.
<!-- add an icon screenshot here -->
View and Style
While having the listing of latest topics may sound tempting, I think it is a bit problematic to follow. Especially with users wanting to learn more about the forum and community, this long list is not very inviting.
Discourse also provides https://forum.gitlab.com/categories which is a split view between categories to select and the latest topics. Imho this adds to a more static layout and ordered boxes where users stay a little longer.
The default views do not allow to select this in the forums, since administrators have hidden it. I'd kindly like to ask to add it back to the menus and also make it the default view (by adding it as first entry to the left).
Admins can do that at https://forum.gitlab.com/admin/site_settings/category/basic
This requires:
- desktop category page style: Categories and Latest Topics
Also, I'd suggest to do the following:
- Default category style: bullet
Categories
Create a new topic
When you create a new topic, the category list is a drop down. For the GitLab Discourse instance, this is a very long list and literally no-one has found APM Monitoring yet.
Structure
Revise categories
- Community contributionshttps://forum.gitlab.com/c/community-contributions/15
- Relatively empty. Maybe rename this to "Integrations" and push them more, e.g. with discussing Tekton and Spinnaker for CI/CD?
- FulFillment https://forum.gitlab.com/t/about-the-fulfillment-category/25765
- I don't understand the idea behind it, the category description is missing. Does it really need its own category?
- News https://forum.gitlab.com/c/announcements/5
- Better move this into "General" and avoid and additional category. Pin the announcements globally, e.g. the hackathon up until it is going to happen. This makes it also visible in the "latest topic" view for everyone.
- ARM Devices https://forum.gitlab.com/c/arm-devices/19
- Not much content, and doesn't logically fit the other categories. I'd suggest removing it and using tags instead, with moving the topics into Questions & Answers.
There's cleanup required for
- https://forum.gitlab.com/c/community-weekdays/25 (latest content from 2015)
- https://forum.gitlab.com/c/fan-art/17 (2016)
Tasks
- Re-organize the categories
- Leave "Questions & Answers" on top
- This solves the problem when no-one selects a category when creating a topic, so it lands in the default category.
- Archive state categories
Trust Levels
Discourse uses trust levels (and Akismet) to prevent spam. The trust levels also add to the gamification feature where a higher grants more permissions and also badges. That way community members can edit posts and "heal" the community without the special need for moderators and administrators.
These trust levels also ensure that e.g. external URLs automatically add rel=nofollow
with search bots not indexing them. Meaning to say, someone advertising on the forums needs to be a trusted member.
Sometimes, these levels are too strict, with only allowing 1 images and 1 URL per new topic. Maybe the default settings need to be adopted a bit, especially for Q&A categories where screenshots can be important to understand a problem.
Tags
They allow better sorting and linking between topics. On forum.gitlab.com they are currently not enabled, so I'd suggest enabling them. Staff can create a basic set of tags, and only users with trust level 1 or above can add new labels. This avoids unexperienced users to create crazy tags.
Gamification
Next to platform specific specifications, community advocates should be able to send appreciation gifts and use general motivation points described at https://about.gitlab.com/handbook/marketing/community-relations/community-advocacy/
Discourse grants badges for specific user actions, learning to use the platform with likes, replies, etc. but also general interaction when joining the conversation.
https://forum.gitlab.com/badges
Custom Badges
One thing I’ve also done for Icinga - custom badges which are awarded manually. This requires manual work and those who actively engage with the community can monitor that.
https://community.icinga.com/t/honoring-your-community-work-icinga-badges-all-the-way/1159
- Community Veteran, being active for quite a while and actively engaged
- Contributor, with having MR(s) merged (needs a sync between gitlab.com usernames and forum user names)
- Technology Partner, developing an integration e.g. an API client, CLI tool, etc. - maybe this invites more developers into the forums as well.
Solved Answer Badges
This is something which encourages members helping others, including myself. The more solved questions there are, the better the feeling is. And with a granted badge you can keep going til the next level.
1, 10, 50, 100 - over time one might need to add 200, 300, 500 and 1000 which can be of the gold level.
https://community.icinga.com/badges/102/helpdesk https://community.icinga.com/badges/104/tech-support https://community.icinga.com/badges/105/support-leader https://community.icinga.com/badges/103/support-hero
https://forum.gitlab.com/badges needs to add them. Since these badge queries are run once per day, existing users will automatically receive these badges earned from the past.
The SQL queries are extracted from here: https://meta.discourse.org/t/discourse-solved-accepted-answer-plugin/30155. Then you’d first need to re-enable the SQL forms via rake console. In case they are needed, I can also add them here including the configuration settings.
Helpdesk
1st accepted answer.
Settings:
SQL:
SELECT p.user_id, p.id post_id, p.updated_at granted_at
FROM badge_posts p
WHERE p.post_number > 1 AND
p.id IN (
SELECT post_id FROM (
SELECT pc.post_id, row_number()
OVER (PARTITION BY p1.user_id ORDER BY pc.created_at) as rnum
FROM post_custom_fields pc
JOIN badge_posts p1 ON p1.id = pc.post_id
JOIN topics t1 ON p1.topic_id = t1.id
WHERE name = 'is_accepted_answer' AND
value IS NOT NULL AND
p1.user_id <> t1.user_id AND
(
:backfill OR
p1.user_id IN (
select user_id from posts where p1.id IN (:post_ids)
)
)
) X WHERE rnum = 1)
Support Hero
100 accepted answers. The silver badges just need adopted counts and other levels.
Settings:
SQL:
SELECT id user_id, current_timestamp granted_at
FROM users
WHERE id IN (
SELECT p1.user_id
FROM post_custom_fields pc
JOIN badge_posts p1 ON p1.id = pc.post_id
JOIN topics t1 ON p1.topic_id = t1.id
WHERE p1.user_id <> t1.user_id AND
name = 'is_accepted_answer' AND
value IS NOT NULL AND
p1.user_id IN (
SELECT user_id
FROM posts
WHERE :backfill OR p1.id IN (:post_ids)
)
GROUP BY p1.user_id
HAVING COUNT(*) > 99
)
Feedback Loop
Sometimes a discussion on the forums leads to existing feature requests or issues. Take the time to comment on the issue, link the forum URL and help product managers and engineers to see the need.
Keep in mind that not everyone in the GitLab team has the time to read through everything on the forums. Provide an abstracted summary of what's going on and help shape community needs with forwarding their (indirect) feedback.
In case there's more information needed, reach out to the discussion participants e.g. via private message, or schedule a Zoom call to better understand the intentions.
Examples:
- https://forum.gitlab.com/t/protect-all-branches-of-gitlab/32931/2 -> gitlab-org/gitlab#18488 (comment 266451426)
- https://forum.gitlab.com/t/lets-encrypt-error/32357/4 -> gitlab-org/omnibus-gitlab#4900 (comment 257734024)
Marketing and Social
Share Community Content on Twitter
Pick the most interesting or attractive topic from the forum and post it via the GitLab account as “From our community channels … blah blah, join the discussion”
Or, do that with your own private Twitter account and raise visibility on the team, like @sytses proposed in a recent group chat. The GitLab Twitter account should then retweet this.
RSS for Categories
Discourse allows users to subscribe to specific categories getting notified about topics then. Also, if you add .rss
to any URL, you can add this feed into your RSS reader.
Buffer and social media tools allow to fetch these RSS feeds too.
Forum Header
You can modify the header in a way to e.g. show coming Events in an iframe. That's done on community.icinga.com for example.
With the newest theming additions in Discourse, one can modify the header even more with custom themes.
Discourse Emails and Marketing
Discourse sends daily digests, when users are not active for a quite while. This includes a summary of missed topics. Also, whenever a user is highlighted or something important is going on, the default is to send an email.
These email templates can be modified by admins at https://forum.gitlab.com/admin/customize/email_templates
Consider adding generic URLs like:
- Events https://about.gitlab.com/events/
- Blog https://about.gitlab.com/blog/
- Trials https://about.gitlab.com/free-trial/
These URLs may contain tracking with UTM codes to measure the origin.
In terms of marketing reach and analysis, administrators can also extract the number of emails sent in the Discourse reports at https://forum.gitlab.com/admin/reports/emails - I bet there are more than 10k mails sent per month, likely 100k even.
Note: This shouldn't become a marketing newsletter from a forum notification. Still, a gentle addition to the email with an "take action" info may also be helpful. Please discuss this opportunity with @melsmo and everyone else :)
Code of Conduct
https://forum.gitlab.com/faq uses the default Discourse CoC but doesn't really name it so. The website provides https://about.gitlab.com/community/contribute/code-of-conduct/ which isn't linked there.
Next to extending the FAQ for asking a question, we could also consider refactoring the Discourse guidelines into a community code of conduct especially for the forums. I have done that for Icinga at https://community.icinga.com/faq#coc
Tasks
- Link https://about.gitlab.com/community/contribute/code-of-conduct/ to the forum's FAQ
- Enhance the forum's FAQ with a more gentle Code of Conduct