From 425b194cf3054fc89fa5d950f0ba1b1f6421314f Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Thu, 6 Feb 2020 18:25:16 +0300 Subject: [PATCH 1/5] Improve CONTRIBUTING.md --- CONTRIBUTING.md | 50 +++++++++++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bbe252df..9b07bc60 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. From 2a46152cbdebd852a10d1fdf58b4856af9a9115b Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Wed, 12 Feb 2020 15:53:19 +0300 Subject: [PATCH 2/5] Update CONTRIBUTING.md Addressed comments --- CONTRIBUTING.md | 45 ++++++++++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b07bc60..8b3458d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,44 +1,63 @@ # 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. +Hi! Nice to have you with us. This guide will walk you through the steps you have 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. +## Before You Start + +The contribution process currently relies on some knowledge of working with Github and writing in Markdown. We understand that this creates a barrier to entry for folks who haven't worked with either of those before. Long term, we hope to provide a solution that can minimise these sorts of barriers. + +We also want to encourage you to dive into Github and Markdown even if you haven't before. We've collected a list of [useful links](#useful-links) that may help you understand both Github and Markdown: + +- [Chaser Pettit's introduction to the GitHub workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962) +- [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax/) +- [Good First Issues](https://github.com/tatianamac/selfdefined/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22good+first+issue%22+) + +Please remember that the contributing team is always here to help. No question is "too simple" or "too easy". We'd rather you ask, as someone else might want to know, too! + +Below we describe two ways for you to get started: through [issues](#version-1-issues) or [pull requests](#version-2-pull-requests). + +--- +**Note:** We also have [documentation](https://www.selfdefined.app/documentation/) that covers development and build processes, provides examples, and describes front matter configurations. + +--- ## 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. +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. +An issue might also be appropriate if you are unsure about some nuances of a definition you want to define. By opening an issue you start a conversation, and that is always a good thing! + +If you are new to Github and feel unsure about what an issue should look like, see examples of a [good first issue](https://github.com/tatianamac/selfdefined/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22good+first+issue%22+). ### 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 pull request (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 that if you are unsure, you can first open an issue or create a PR, include «WIP» in the title («WIP» stands for «work in progress»), 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). + For this tutorial we will take the word «Obsessive Compulsive Disorder», as it allows us to show some of the features. That means we would create the file named `obsessive-compulsive-disorder.md`. As it is already defined, you can have a look at the [finished definition of «Obsessive Compulsive Disorder»](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: + Every definition _needs_ to have the following 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». + - `title` is a word or a phrase you are defining. In this example 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`. + - `slug` is a string that we'll use to link to this word. It should be a URL-friendly, all-lowercase hyphenated version of the full title. In our example it's `obsessive-compulsive-disorder`. - - `defined` flag can either be `true` or `false`. As soon as you set it to `true`, your definition will be visible. + - `defined` flag can either be `true` or `false`. As soon as you set it to `true`, your definition will be visible on our website. - - `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`. + - `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 our example it is a `noun`. This leaves us with the following front matter: @@ -52,7 +71,7 @@ After you’ve forked the repo, you will need to write a definition. Good times. ``` -[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. +[The finished definition of «Obsessive Compulsive Disorder»](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 From 5e54d82ac2b5e1e5ce203a6b9bab8fd90896b87e Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Wed, 12 Feb 2020 15:54:52 +0300 Subject: [PATCH 3/5] Removed wrong link --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b3458d8..bf7cb41e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Hi! Nice to have you with us. This guide will walk you through the steps you hav The contribution process currently relies on some knowledge of working with Github and writing in Markdown. We understand that this creates a barrier to entry for folks who haven't worked with either of those before. Long term, we hope to provide a solution that can minimise these sorts of barriers. -We also want to encourage you to dive into Github and Markdown even if you haven't before. We've collected a list of [useful links](#useful-links) that may help you understand both Github and Markdown: +We also want to encourage you to dive into Github and Markdown even if you haven't before. We've collected a list of useful links that may help you understand both Github and Markdown: - [Chaser Pettit's introduction to the GitHub workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962) - [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax/) From 950925a255c8cec43109b4fe879e1e3ed3958587 Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Thu, 13 Feb 2020 12:29:05 +0300 Subject: [PATCH 4/5] Update CONTRIBUTING.md Add help info and fix style --- CONTRIBUTING.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf7cb41e..f036edad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ We also want to encourage you to dive into Github and Markdown even if you haven - [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax/) - [Good First Issues](https://github.com/tatianamac/selfdefined/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22good+first+issue%22+) -Please remember that the contributing team is always here to help. No question is "too simple" or "too easy". We'd rather you ask, as someone else might want to know, too! +Please remember that the contributing team is always here to [help](#get-help). No question is "too simple" or "too easy". We'd rather you ask, as someone else might want to know, too! Below we describe two ways for you to get started: through [issues](#version-1-issues) or [pull requests](#version-2-pull-requests). @@ -25,7 +25,7 @@ Below we describe two ways for you to get started: through [issues](#version-1-i ### 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. +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. By opening an issue you start a conversation, and that is always a good thing! @@ -37,13 +37,15 @@ You got a definition and want to define it. That’s awesome. Let’s go. Curren #### Working on Words -After you’ve forked the repo, you will need to write a definition. Good times. Hopefully. Always remember that if you are unsure, you can first open an issue or create a PR, include «WIP» in the title («WIP» stands for «work in progress»), and ask for early feedback. +After you’ve forked the repo, you will need to write a definition. Good times. Hopefully. + +Always remember that if you are unsure, you can first open an issue or create a PR with «WIP» in the title («WIP» stands for «work in progress») and ask for early feedback. For example, it might be called *«\[WIP\] Propose definition for spirit animal»*. - 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 we will take the word «Obsessive Compulsive Disorder», as it allows us to show some of the features. That means we would create the file named `obsessive-compulsive-disorder.md`. As it is already defined, you can have a look at the [finished definition of «Obsessive Compulsive Disorder»](11ty/definitions/obsessive-compulsive-disorder.md). + For this tutorial we will take the word «Obsessive Compulsive Disorder», as it allows us to show some of the features. That means we would create the file named `obsessive-compulsive-disorder.md` (as it is already defined, you can have a look at the [finished definition of «Obsessive Compulsive Disorder»](11ty/definitions/obsessive-compulsive-disorder.md)). - Step 2: Populate the file you created. @@ -76,3 +78,11 @@ After you’ve forked the repo, you will need to write a definition. Good times. #### 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. + +## Get Help + +If you've already tried reading through our [documentation](https://www.selfdefined.app/documentation/) and are stuck, we're here to help and ask your questions: + +- Reach out to [@SelfDefinedApp](https://www.twitter.com/selfdefinedapp) on Twitter. +- File an [issue](https://github.com/tatianamac/selfdefined/issues/new) if you think our docs are missing some information that might be helpful. +- Contact . From ff63f7eb706ce12c6d3f9e925f8d72f8aecfba51 Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Thu, 13 Feb 2020 13:03:17 +0300 Subject: [PATCH 5/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f036edad..75a8b2e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,11 +41,13 @@ After you’ve forked the repo, you will need to write a definition. Good times. Always remember that if you are unsure, you can first open an issue or create a PR with «WIP» in the title («WIP» stands for «work in progress») and ask for early feedback. For example, it might be called *«\[WIP\] Propose definition for spirit animal»*. -- Step 1: Create a file named `word.md` in in the [definitions folder](11ty/definitions/) where we store all definitions. +For this tutorial we will take the word «Obsessive Compulsive Disorder», as it allows us to show some of the features. - `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`. +- Step 1: Create a file named `word.md` in the [definitions folder](11ty/definitions/) where we store all definitions. - For this tutorial we will take the word «Obsessive Compulsive Disorder», as it allows us to show some of the features. That means we would create the file named `obsessive-compulsive-disorder.md` (as it is already defined, you can have a look at the [finished definition of «Obsessive Compulsive Disorder»](11ty/definitions/obsessive-compulsive-disorder.md)). + Replace `word` with the word or the phrase you are defining. Write it in all-lowercase letters with hyphens instead of spaces. + + In our example, we would create the file named `obsessive-compulsive-disorder.md` (as it is already defined, you can have a look at the [finished definition of «Obsessive Compulsive Disorder»](11ty/definitions/obsessive-compulsive-disorder.md)). - Step 2: Populate the file you created. @@ -53,11 +55,11 @@ Always remember that if you are unsure, you can first open an issue or create a Every definition _needs_ to have the following meta information: `title`, `slug`, `defined`, and `speech`. Let's discuss what each of these mean: - - `title` is a word or a phrase you are defining. In this example it's «Obsessive Compulsive Disorder». + - `title` is a word or a phrase you are defining. In this example it's «Obsessive Compulsive Disorder». - - `slug` is a string that we'll use to link to this word. It should be a URL-friendly, all-lowercase hyphenated version of the full title. In our example it's `obsessive-compulsive-disorder`. + - `slug` is a string that we'll use to link to this word. It should be a URL-friendly, all-lowercase hyphenated version of the full title. In our example it's `obsessive-compulsive-disorder`. - - `defined` flag can either be `true` or `false`. As soon as you set it to `true`, your definition will be visible on our website. + - `defined` flag can either be `true` or `false`. As soon as you set it to `true`, your definition will be visible on our website. - `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 our example it is a `noun`.