Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Writer's Guide #1277

Merged
merged 2 commits into from
Jul 2, 2017
Merged

Update Writer's Guide #1277

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
291d087
I think the guideline is missing this imp part
cool88 Jun 8, 2017
4eb461c
docs(writers-guide): tweak writers-guide and add section on YAML fron…
skipjack Jul 2, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 37 additions & 4 deletions content/writers-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,49 @@
title: Writer's Guide
---

The following sections contain all you need to know about editing and formatting the content within this site. Make sure to do some research before starting your edits or additions. Sometimes the toughest part is finding where the content should live and determining whether or not it already exists.


## Process

1. Check related issue if an article links to one.
2. Hit `edit` and expand on the structure.
3. PR changes.


## YAML Frontmatter

Each article contains a small section at the top written in [YAML Frontmatter]():

``` md
---
title: My Article
sort: 3
contributors:
- [github username]
related:
- title: Title of Related Article
url: [url of related article]
---
```

Let's break these down:

- `title`: The name of the article.
- `sort`: The order of the article within its section.
- `contributors`: A list of GitHub usernames who have contributed to this article.
- `related`: Any related reading or useful examples.

Note that `related` will generate a __Further Reading__ section at the bottom of the page and `contributors` will yield a __Contributors__ section below it. If you edit an article and would like recognition, please feel free to add your GitHub username to the `contributors` list.


## Article Structure

1. Brief introduction - a paragraph or two so you get the basic idea. Tell what you are going to tell.
2. Main content - tell what you promised to tell.
3. Conclusion - tell what you told and recap the main points.
4. References - link to related articles and external resources so people can read and learn more about the topic.
1. Brief Introduction - a paragraph or two so you get the basic idea about the what and why.
2. Outline Remaining Content – how the content will be presented.
3. Main Content - tell what you promised to tell.
4. Conclusion - tell what you told and recap the main points.


## Running the Site

Expand All @@ -23,6 +54,7 @@ title: Writer's Guide

The site will update itself as you make changes.


## Typesetting

* webpack should always be written in lower-case letters. Even at the beginning of a sentence. ([source](https://github.com/webpack/media#name))
Expand All @@ -31,6 +63,7 @@ The site will update itself as you make changes.
* Use "webpack 2" to refer to a specific webpack version (~~"webpack v2"~~)
* Use ES5; ES2015, ES2016, … to refer to the ECMAScript standards (~~ES6~~, ~~ES7~~)


## Formatting

### Code
Expand Down