mafoo.org.uk/selfdefined
1
0
Fork 0
mirror of https://github.com/fooflington/selfdefined.git synced 2025-01-22 17:30:00 +00:00
Code Issues Projects Releases Wiki Activity

Improve CONTRIBUTING.md

Browse Source
This commit is contained in:
Ekaterina Mekhnetsova 2020-02-06 18:25:16 +03:00 committed by GitHub
parent 43e33f418b
commit 425b194cf3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
CONTRIBUTING.md
View File

@ -2,44 +2,58 @@
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 aware that this poses a problem for most people and are discussing how a more inclusive contribution process could look like.
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. We can then collectively figure out how to best get this word defined.
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).
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.
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.
All definitions are stored in the [definitions folder](11ty/definitions/). Create a file named `word.md` in it. `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 feature. That means I would create the file `obsessive-compulsive-disorder.md` (as it is a defined word, you can have a look at [the finished definition](11ty/definitions/obsessive-compulsive-disorder.md)).
- Step 1: Create a file named `word.md` in in the [definitions folder](11ty/definitions/) where we store all definitions.
All definitions consist of two parts: Front Matter and content. Front Matter is technical bubble for some structured data about your content. [You can find the complete documentation on our website](https://www.selfdefined.app/documentation/front-matter/). Here’s a quick run down:
`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`.
Every definition _needs_ to have a `title`. In my case «Obsessive Compulsive Disorder». And a slug. That’s the string we need to link somewhere. And it needs a `slug`. A slug is URL friendly, hyphenated version of the title. In my case: `obsessive-compulsive-disorder`. The third required item is the `defined` flag. This is either `true` or `false`. As soon as you set it to `true` your definition will be visible. Finally we need to what kind of word your word. A noun? Or adjective? That’s what `speech` is for. In my example it is a noun.
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).
This leaves us with the following front matter:
- Step 2: Populate the file you created.
```yaml
---
title: Obsessive Compulsive Disorder (OCD)
slug: obsessive-compulsive-disorder
defined: true
speech: noun
---
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`.
[The finished definition](11ty/definitions/obsessive-compulsive-disorder.md) has some more content. I encourage you to take a look around, add things to your word and see what happens on the page.
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, which you can take as the baseline for your work. Take a look at the [File Examples section of our documentation](https://www.selfdefined.app/documentation/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.