How to Contribute

Hello! Thank you for wanting to be part of this project.

Whether you're fixing a typo, adding a page, or improving the layout - every contribution helps. This guide will walk you through the basics of how to get involved.

If this is a bit much for you, that's okay. Feel free to shoot me an email at [email protected] about your suggestion(s) and I'll get to it when I can.

The Repository

All the docs (including this page!) are live on GitHub:
👉 https://github.com/thebenb/the-docs

You'll need an account to contribute.

Once you're signed in, you can either:

• Edit files directly in the browser (great for most people)

• Fork the repo and make changes locally if you prefer working in your own editor. I'd only suggest this if you know what you're doing.

Making a Pull Request

To suggest changes, you'll make a pull request (PR), which is a lot like sending a proposal.

It's a lot like saying: "Here's what I changed, could you add it to the site?"

Steps:

1. Click "Edit" on the file you want to change (you'll be creating a fork automatically if you don't already have one).

2. Make your changes.

3. Scroll down and write a short title + optional description describing what you have done.

4. Click "Propose changes".

5. Open a pull request.

All changes need to be reviewed and approved before they go live. This keeps things consistent and avoids surprises. Other than myself (Ben), a very limited set of trusted people will have permission to approve posts.

Please make separate PRs for each proposed change / file. Failure to do so may lead to rejection of your work (which I'd hate to do!).

---

Writing Style

• Aim for a tone that's clear, informative, and helpful.

• It should feel somewhat professional, some fun and personality is totally fine.

• Avoid anything overly aggressive, dismissive, or biased - this is a collaborative space at the end of the day. As much as I personally dislike "twitch clipper repost channels" and such, they still exist and should be acknowledged.

• If you're sharing an opinion or an anecdote, make it obvious (e.g. "I prefer…" or "In my experience…").

• Don't assume that readers are stupid, but keep in mind that they may need things to be explained briefly at times.

• Don't rely on AI to write stuff for you. If you by chance use AI to write something, please clearly disclose that like I did with this page.

Writing in Markdown

This project uses Markdown to format content. It's simple and looks like this:

# Heading 1
## Heading 2
**bold**, *italic*, `inline code`

- Bullet points
1. Numbered list
> Blockquote


Links:

[link text](https://example.com)

You may find it familiar as Discord and Reddit allow it to some extent.

Need a quick reference? 👉 https://www.markdownguide.org/cheat-sheet/

There are plenty of markdown-writing programs and websites out there that can help you out. Hell, even Google Docs can export markdown now!

Using Admonitions

Admonitions are special blocks like the one at the top of this page. They help call out notes, tips, warnings, etc.

The warning at the top of the page looks like this in markdown:

:::warning

**Warning:**

The above markdown explanation was written by AI, but was proofread and adjusted slightly by Ben.
:::

You can use:

Use them when you want to highlight something important or make a page easier to scan.

These admonitions are coded in separately to the Markdown renderer, so I can add/remove admonitions as I please. Feel free to contact me if you would like more.

Adding media

If you're fancy and would like to insert images, videos, etc. in your submission, please ensure that the media is located within /media/ in the repo, and linked to appropriately. Below is an example on how to do that in Markdown.

![](/media/your_image.png)

GitHub typically doesn't like file submissions over 25MB, and realistically, we shouldn't be subjecting viewers to such big files anyway.

Please try to compress your images to an appropriate size, for both the sake of potential readers and whichever poor little server I run this website on.

Again, if you have concerns or find something too complex / advanced for you, don't worry! I'm happy to handle your submission directly if you email [email protected] with your suggestions. Submissions handled this way will have the best-practices applied for you, so no need to stress.

---

Final notes

Thanks again for contributing (or even just thinking about doing so).

A lot of this project will likely go overlooked and under-appreciated, especially the contributors, so reading through this really does mean a lot. Thanks.