matrix-org / matrix-org/matrix.org

Simplify the TWIM Guide

Open
#3,248 2 comments 1 reaction 0 assignees View on GitHub
enhancement good first issue help wanted missing content
Dominant language
JavaScript
Stars
616
Forks
463
Avg merge
2d 3h
Merged PRs (30d)
19

Description

At the moment, the [TWIM Guide](https://matrix.org/twim-guide/) is a bit of a wall of text. It is nice to have an exhaustive list of things we want people to do, but it can be overwhelming for newcomers.

To keep TWIM welcoming and not discourage people from posting their updates, we could adopt a simpler "10 things to know" approach, that could look like the server rules in e.g. https://mastodon.social/about

I would suggest the following items

1. Follow the Matrix.org Code of Conduct.
2. Mention the bot `@this-week-in:matrix.org`, and then write what you want to share about your project.
3. Use markdown to write your entry. The bot expects markdown, and you'll make the editors' life much easier!
4. Start your titles with `### `. Your posts are embedded in a blog post page, and it makes everything more legible.
5. You can submit multiple entries, about the same project or different projects.

And then point to the rest of suggestions we give, below.

Contributor guide

Open the contributing guide

Research direction

Start by locating the source for the TWIM Guide at https://matrix.org/twim-guide/ and review how its current suggestions are organized. Simplify the introductory guidance into the proposed “10 things to know” list, then point readers to the remaining suggestions. Done means the guide is less overwhelming while retaining access to the full advice.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.