mirror of
https://github.com/fooflington/selfdefined.git
synced 2025-01-22 17:30:00 +00:00
60 lines
3.7 KiB
Markdown
60 lines
3.7 KiB
Markdown
# Contributing Guidelines
|
||
|
||
Hi! Nice to have you with us. This file will walk you through the steps you need to take if you want to contribute a word or some code to the project. Let’s go.
|
||
|
||
Actually – before we start – a quick word of caution: unfortunately, the contribution process involves some technical knowledge. We are aware that this poses a problem for most people and are discussing how a more inclusive contribution process could look like.
|
||
|
||
## Contributing Words
|
||
|
||
### Version 1: Issues
|
||
|
||
If you know a word that should be defined, but – for whatever reason – don’t feel confident writing the definition yourself (or maybe you disagree with an existing defintion), please open an [issue](https://github.com/tatianamac/selfdefined/issues/new). We can then collectively figure out how to best get this word defined.
|
||
|
||
An issue might also be appropriate if you are unsure about some nuances of a definition you want to define.
|
||
|
||
### Version 2: Pull Requests
|
||
|
||
You got a definition and want to define it. That’s awesome. Let’s go. Currently, you need to fork this repository and open a PR out of your fork. If that sounds like gibberish to you, Chaser Pettit wrote a [great introduction to the workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
|
||
|
||
#### Working on Words
|
||
|
||
After you’ve forked the repo, you will need to write a definition. Good times. Hopefully. Always remember, if you are unsure, you can first open an issue or create a PR, include «WIP» in the title, and ask for early feedback.
|
||
|
||
- Step 1: Create a file named `word.md` in in the [definitions folder](11ty/definitions/) where we store all definitions.
|
||
|
||
`word` should be the name of the word you are defining. Not `word`. Except you are defining «word». In this case it should be `word`.
|
||
|
||
For this tutorial I will take the word «Obsessive Compulsive Disorder», as it allows me to show some of the features. That means I would create the file `obsessive-compulsive-disorder.md`. As it is already defined, you can have a look at the [finished definition](11ty/definitions/obsessive-compulsive-disorder.md).
|
||
|
||
- Step 2: Populate the file you created.
|
||
|
||
All definitions consist of two parts: **front matter** and **content**. Front Matter is a technical bubble for some structured data about your content. On our website you can find the [complete documentation on Front Matter](https://www.selfdefined.app/documentation/front-matter/). Here’s a quick run down:
|
||
|
||
Every definition _needs_ to have this meta information: `title`, `slug`, `defined`, and `speech`. Let's discuss what each of these mean:
|
||
|
||
- `title` is easy. In my case it's «Obsessive Compulsive Disorder».
|
||
|
||
- `slug` is a string that we'll use to link to this word. It should be a URL-friendly, hyphenated version of the title. In my case: `obsessive-compulsive-disorder`.
|
||
|
||
- `defined` flag can either be `true` or `false`. As soon as you set it to `true`, your definition will be visible.
|
||
|
||
- `speech` stores information about the word's part of speech. What kind of word you are defining? A noun? Or an adjective? That’s what `speech` is for. In my example it is a `noun`.
|
||
|
||
This leaves us with the following front matter:
|
||
|
||
```yaml
|
||
---
|
||
title: Obsessive Compulsive Disorder (OCD)
|
||
slug: obsessive-compulsive-disorder
|
||
defined: true
|
||
speech: noun
|
||
---
|
||
|
||
```
|
||
|
||
[The finished definition](11ty/definitions/obsessive-compulsive-disorder.md) has some more content. We encourage you to take a look around, add things to the file with your word's definition, and see what happens on the page.
|
||
|
||
#### Pre-Made File Examples
|
||
|
||
We have created some examples that you can use as the baseline for your work. Take a look at the [File Examples](https://www.selfdefined.app/documentation/examples/) section of our documentation.
|