Improve/expand contribution instructions

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,11 +1,11 @@
 ## Distro Proposal
 
-If you're making a  distribution proposal, check off the following as you go to ensure it's good to go.
+If you're proposing the addition of a new distribution, check off the following as you go, to ensure the pull request is good to merge.
 
-- [ ] I've read the [instructions for contributing a post](/CONTRIBUTING.md)
-  - [ ] filled in the required metadata on my post
-  - [ ] included a plain desktop screenshot with no additional windows (if applicable)
-  - [ ] did not "give a review" when writing a post
+- [ ] I've read the [instructions for contributing an entry](/CONTRIBUTING.md)
+- [ ] I filled in the required metadata on my post
+- [ ] I included a plain desktop screenshot with no additional windows (if applicable)
+- [ ] I wrote the post in a neutral, objective language
 
 <!-- You can delete all of the above in your pull request -->
 
@@ -17,9 +17,9 @@ If you're making a  distribution proposal, check off the following as you go to
 
 ## Page Metadata Updates
 
-If you're just updating information/metadata on a page make sure you do the following:.
+If you're just updating information/metadata on a page, make sure you do the following:
 
-- [ ] update the screenshot file to the latest version (if applicable) and please optimize the file size
-- [ ] update or add the `updated:` field to the post's frontmatter with the date in `YYYY-MM-DD` format
-- [ ] update or add the `updater:` field to the post's frontmatter with your name in quotations `"Your Name"`
-- [ ] rename the post's filename with the new date, e.g `YYYY-MM-DD-name`
+- [ ] add a screenshot file for the latest version (if applicable) and please optimize the file size
+- [ ] update or add the `updated:` field to the post's frontmatter with the date of your pull request, in `YYYY-MM-DD` format
+- [ ] update or add the `updater:` field to the post's frontmatter with your name in quotes: `"Your Name"`
+- [ ] rename the post's filename to match the `updated:` field, e.g `YYYY-MM-DD-name`

CONTRIBUTING.md

@@ -1,14 +1,18 @@
 # Contributing to Compute Freely
 
+This site is powered by [Jekyll](https://jekyllrb.com/), and its basic structure is a set of fixed pages (Home, About, Switching, etc.), along with some dynamically generated list pages like Tags and Categories, and then the bulk of the content lies on individual posts, one per distribution. See [Directory Structure](https://jekyllrb.com/docs/structure/) in the Jekyll docs to learn more about this setup.
+
+This blog-like approach for the distribution pages allows making use of Jekyll's features for dynamic, dated content, including built-in support for metadata like the publication date and authors of the text, showing a banner for content that is potentially outdated, etc.
+
 ## Submitting distributions
 
-Submitting a new distribution pages is simply a matter of writing a new post and adding it to the `_posts` folder. When writing a post for a distribution you would like to submit, you are free to editorialize, but if you gather information from the project's website to fill out the post paraphrase as best you can opposed to copying straight from it.
+Submitting a new distribution page is simply a matter of writing a new post and adding it to the `_posts` folder. When writing a post for a distribution you would like to submit, you are free to author the text yourself (making sure to keep a neutral and objective tone); however, but if you choose to use information from the project's website to fill out the post, paraphrase the content instead of copying straight from it.
 
-For your convenience a template is included in the `_drafts` folder.
+For your convenience, a template post is included in the `_drafts` folder.
 
 ### Metadata
 
-Each post has "frontmatter" that contains metadata for the post and about the distribution in general that shows up on the individual pages for each. Here's an example from the post for Ubuntu.
+Each post has a [frontmatter](https://jekyllrb.com/docs/front-matter/) section that contains [YAML](https://yaml.org/)-formatted metadata for the post and about the distribution in general. This information shows up as  on the individual pages for each. Here's an example from the post for Ubuntu.
 
 ```yaml
 layout: distro
@@ -35,28 +39,31 @@ notes:
       url: https://community.ubuntu.com/
 ```
 
-#### Publishing
+#### Publication metadata
 
-The first half of the frontmatter contains publishing and categorization information.
+The first half of the frontmatter contains publishing and categorization information for the post.
 
-- `layout` is the page layout for Jekyll. **Do not change this**
-- `title` in this case will refer to the distribution name
-- `date` is the date of publication (addition)
+- `layout` (always `distro`) is the page layout for Jekyll
+- `title` is the distribution name
+- `date` is the date of publication of the post (i.e. addition of the distribution to this project)
+- `updated` is the date of the last update to the post (e.g. changing the version, fixing a typo, etc.)
+- `updater` is the name of the person who last updated the post
 - `logo` is the file name of the logo that you provide (minus the extension)
-- `image` is the filename of the screenshot you provide
+- `image` is the filename of the screenshot you provide (including the extension)
 - `caption` is an optional description of the screenshot
-- `tags` are an array of tags for the post, these should be limited to things like the desktop environments it uses, it's primary purpose (e.g. server, desktop, enterprise), a one-word estimation of it's difficulty
+- `tags` is an array of tags for the post. These should be limited to things like its primary purpose (e.g. `server`, `desktop`, `enterprise`)
+- `category` is a one-word estimation of the distribution's approachability (`beginner`, `intermediate` or `advanced`)
 
-#### Notes
+#### Distribution metadata
 
-The `notes` section contains pertinent info about a distribution that show's up in the 'Notes' section on each post.
+The `notes` section contains pertinent info about the distribution itself that shows up in the “Notes” section on each post.
 
 - `homepage` is the complete url of a distribution's homepage
 - `version` is the current version at the time of publication
 - `based-on` is a list of distributions that this one is based on (if any)
-- `desktops` is a list of all default desktops arranged in an array, i.e. if a distribution provides multiple spins that are of different desktop environments you list those here
-- `install` is the mode of installation — either "graphical", "command line" or "live"
-- `developers` name the primary developer or developers of the distribution and optionally provide a url
+- `desktops` is an array of all default desktop environments provided by the distribution
+- `install` is the mode of installation — either “graphical”, “command line” or “live”
+- `developers` is the name (and optionally an URL) of the primary developer or developers of the distribution
 
 ### Including image assets
 
@@ -78,7 +85,7 @@ An acceptable version of the project logo must:
 
 ## Updating an existing post
 
-If you're simply updating an existing post, make the changes to the post as necessary but don't remove the original author's name from `author` or change the `date:` field (this is to keep track of the original), simply add the following lines:
+If you're simply updating an existing post, make the changes to the post as necessary but don't remove the original author's name from `author` or change the `date:` field (this is to keep track of the original); simply add the following lines:
 
 ```yaml
 updated: "YYYY-MM-DD"
@@ -90,3 +97,5 @@ Then rename the post file with the `updated:` date.
 ## Other contributions
 
 Overall improvements to the site are gladly accepted as well and can be made via a general pull request.
+
+To make style or structure changes, it's best to have a basic understanding of how Jekyll works. The [Jekyll documentation](https://jekyllrb.com/docs/) is generally pretty comprehensive and readable, so it will probably be a useful resource for those wanting to do these types of contributions.

README.md

@@ -18,6 +18,6 @@ bundle exec jekyll serve
 
 ## Contributing
 
-Contributions are obviously welcome! If you would like to contribute to this project, please have [read this](/CONTRIBUTING.md) regarding contributions.
+Contributions are quite welcome! If you would like to contribute to this project, please [read the contribution guidelines](/CONTRIBUTING.md).
 
-Alternatively, if you would like to support development by making a donation you can do so [here](https://snwh.org/donate).
+Alternatively, if you would like to support development by making a donation, you can do so [here](https://snwh.org/donate).