Contribution Style Best Practices

This content is not available in your language yet.

This is a guide on how to structure your contributions to the wiki! Ensuring that the content you create is accessible and structered correctly. Though please keep in mind that contributions are always wanted! There are no consequences for getting things wrong; at most, we might ask you to tweak a few things.

With all that said, let’s go over how to structure your pages!

There are two main types of contributions you’d be wanting to make:

Single-page short overviews and guides
Multi-page projects and tutorials

Depending on what you’re adding, some things will change, but we’ll cover everything!

First, let’s cover how to approach and think about what we’re going to write

Writing the content

We’ll cover all the things you can add to your contribution, but what about writing the content itself? Unfortunately, this is a hard thing to define with strict rules and examples! But, our focus is to engage and teach those who come to the wiki looking to learn!

One of the best approaches to writing this kind of material is the Diátaxis approach which we highly recommend you take the time to read!

In most of our resources, we’re taking the Tutorial approach as outlined by Diátaxis. This means that the learner, the person engaging with your resource, should learn through Doing. They should come out the other end with something they’ve Made with your resource serving to guide them through the process of this creation. However, we should never be withholding information under the guise of the reader “Figuring it out themselves.” Our role as resource creators is to provide a structured and safe environment for the reader to learn and create. Often even identifying potential mistakes or pitfalls the reader could encounter, and addressing them in the tutorial.

You’ll also find Reference style pages on the wiki (Such as the page on Classes and object oriented programming) Which contain direct, clear and referenceable information about a particular topic.

You may even find pages that fit best under the How-To guide category (This page for example) or the Explanation category!

What’s most important, is knowing what type of page you’re setting out to right, and how to approach writing it.

Take a look at the Diátaxis approach figure out which category your contribution fits best under, take some time to understand what it should and shouldn’t have, and then get stuck in!

We can’t wait to see what you write! Let’s move onto how to structure and style your contribution! Starting with adding a new page.

Adding a new page to the wiki

Adding a page is simple! However it’ll be different depending on if you just want a single page guide, or if you want to make a multi-step tutorial. Generally large projects should always be multi-page tutorials, whereas small guides about single topics should be single pages.

Adding one page

To add a page, you’ll want to open up the local copy of the Wiki you’ve cloned, and find the folder that matches the topic you want to add your page to! You’ll add a new page, name it something about your topic, and end it with .mdx

For example, if I wanted to make a page for Godot about setting up a third-person camera, i’d do something like:

Directorysrc/
- Directorycontent/
  - Directorygodot/
    3rdPersonCam.mdx

In this page, you’ll at the very top want to add something like this:

---
title: 3rd Person Camera Setup
description: A guide on how to set up a third-person camera for Godot
---

The Title will be what actually shows up in the navigation bar, so keep it short, but descriptive!

Making a multi-page tutorial

Making a multi-page tutorial is a little more involved, and has a few more things you’ll need to do to make it work! If you get confused, take a look at the Godot Dungeon Crawler, and see how that’s set up.

First, you’ll again want to navigate to the folder for the subject you want to cover, though this time you’ll create a folder to hold your pages, named something relevant to your tutorial.
Inside this, you’ll want to create a folder for each page/step in your tutorial, with the names of the pages starting with the step number, starting from 0.
Inside each of these folders, you’ll want a page called index.mdx
That’s a lot of steps! So here’s an example of how that might look if you were making a tutorial on making a 3rd person game in Godot with health and enemies
- Directorysrc/
  - Directorycontent/
    …
  - Directorygodot/
    Directory3rdPersonGame/
    Directory0-setup/
    index.mdx
    Directory1-3rdPersonCam/
    index.mdx
    Directory2-health/
    index.mdx
    Directory3-enemies/
    index.mdx
Each of these pages should have headings that look like something like this:
```
---
type: tutorial
unitTitle: Getting started
title: Setting up our scene
description: Creating our player scene and scripts
---
```
The type should always be tutorial

The unitTitle is what will show up on the right-side navigation for your tutorial.
The final, and most complicated step, is to add a link to your 0 folder inside astro.config.mjs

If you take a look at the file, you’ll get a pretty good idea of how it should look! Find the section that has the label for your topic, and add a link, which for our example would be under label: "Game Design" and would look something like this:
```
    {
        label: "3rd Person Game",
        link: "game-design/godot/3rdPersonGame/0-setup/"
    },
```
Test your addition using npm run dev and see if it shows up!

Remember: There are no consequences to getting this wrong! Try and solve any errors you get, and if you get stuck, ask for help!

Headings

Headings denote new major sections of your contribution, and should be used only for distinct sections covering something new. They create new major sections on the right-side navigation bar, to allow for easy navigation between the important sections of your contribution.

Headings can be added like this:

## Your heading here

Sub-Headings

Sub-headings work similarly to Headings, and denote new sections Within the topic designated by the heading. These should be used to break down the major topic into sub-topics or sections. They also create sub-sections on the right-side navigation bar, allowing for navigation between the sub-headings.

Sub-headings can be added like this:

### Your sub-heading here

Note that a sub-heading will belong to the nearest Heading Above it

Headings and sub-headings should be used to control the flow of your contribution, and prevent it from becoming one big wall of text. They can let the reader know when they’re moving onto something new, and also allow them to quickly jump between sections!

Notes and Tips

Notes and Tips can be used to add extra information or context in a way that stands out to the reader as being important!

Notes are great for Information like if the guide will only work with a particular version of software!

Tips on the other hand are great for providing some extra information to the reader, such as where to find a particularly hard-to-find feature, or a time-saving suggestion, or even just something you’ve learnt through trial and error.

Notes look like this:

and are added like this:

:::note[Note heading]
Note text, here is where your information will be!
:::

and Tips look like this:

and are added like this:

:::tip
Here's a useful tip!
:::

Think of notes and tips as a way to add extra context for the reader. Notes fit great below a heading or sub-heading to provide context for a situation. Tips work great after asking the reader to do something, or explaining how something works.

Inserting Code

One of the most important things to make sure your contribution is useful and easy to follow is the way you integrate the code you want the reader to write!

Adding code itself is easy, and can be done using Backticks like this:

```
print("hello")
print("World!")
```

You can also optionally denote a language for syntax highlighting, for example

```python
print("hello")
print("World!")
```

Would look like this:

print("hello")
print("World!")

When to add code

It’s important when going over code that you show each new section on its own, as well as showing the script in its entirety at the end. This helps to give the reader context for what they’ve just added. For example:

Let’s add the variables:
```
a = 1
b = 2
```
Then we’ll create a function
```
def add():
    print(a + b)
```
Giving us this so far:
```
a = 1
b = 2

def add():
    print(a + b)
```

Steps

Steps are another important way to ensure that your guide is clear and readable! Infact you’ve already seen them used in the step before! Steps should always be used when covering a multi-step process, and are often a great fit under a sub-heading!

First, to use steps, you’ll need to import the required module. This can be done by adding

import { Steps } from '@astrojs/starlight/components';

To the top of each page using steps!

Steps can be added like this:

<Steps>
1. First step title
    Here's the content of the first step
    steps can be as long as you want!
2. Second step title
    They can even contain other things covered in this guide, such as codeblocks
    ```python
        print("hello world!")
    ```
3. Third step title
    Steps allow the reader to nicely follow along, and should be used where applicable
</Steps>

Multi-page tutorials

The content in the next two sections is mostly applicable to multi-page tutorials, but can still be useful to understand even if you’re only writing a single page guide!

Checklists

The end of every page of multi-step tutorials must have a checklist. Which first need to be imported using:

import Box from '/src/components/tutorial/Box.astro';
import Checklist from '/src/components/tutorial/Checklist.astro';

Checklists will look like this:

Checklist name

I’ve read this doc
I’m ready to add my awesome idea to the wiki

and are added like this:

<Box icon="check-list">

### Checklist name
<Checklist>
- [ ] I've read this doc
- [ ] I'm ready to add my awesome idea to the wiki
</Checklist>
</Box>

Need help?

Take a look at other pages on the wiki, and see how they work! Remember, changing things on your local copy Only changes them for you! So there’s no risk to messing around and figuring out how things work! Just make sure you don’t submit those changes when it’s time to create a Pull Request!

If you have any questions about contributing, or need help with anything, everyone in our Discord would be more than happy to give you some pointers!

Also remember to read the documentation! The Starlight and Astro docs have a ton of information about how to build wiki pages.