This repository has been archived by the owner. It is now read-only.
Browse files

Initial commit of Plain Language Tutorial

  • Loading branch information...
kategarklavs committed Feb 5, 2016
0 parents commit 0bb28ca41c9e27f89fa63cdedd8d1fc5cdb375ea
@@ -0,0 +1,5 @@
@@ -0,0 +1,19 @@
## Welcome!

We're so glad you're thinking about contributing to an 18F open source project! If you're unsure about anything, just ask -- or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We love all friendly contributions.

We want to ensure a welcoming environment for all of our projects. Our staff follow the [18F Code of Conduct]( and all contributors should do the same.

We encourage you to read this project's CONTRIBUTING policy (you are here), its [LICENSE](, and its [README](

If you have any questions or want to read more, check out the [18F Open Source Policy GitHub repository](, or just [shoot us an email](

## Public domain

This project is in the public domain within the United States, and
copyright and related rights in the work worldwide are waived through
the [CC0 1.0 Universal public domain dedication](

All contributions to this project will be released under the CC0
dedication. By submitting a pull request, you are agreeing to comply
with this waiver of copyright interest.
10 Gemfile
@@ -0,0 +1,10 @@
source ''

gem 'jekyll'
gem 'redcarpet'
gem 'rouge'
gem 'go_script'

group :jekyll_plugins do
gem 'guides_style_18f'
@@ -0,0 +1,63 @@
colorator (0.1)
ffi (1.9.10)
go_script (0.1.5)
bundler (~> 1.10)
safe_yaml (~> 1.0)
guides_style_18f (0.3.0)
htmlentities (4.3.4)
jekyll (3.0.0)
colorator (~> 0.1)
jekyll-sass-converter (~> 1.0)
jekyll-watch (~> 1.1)
kramdown (~> 1.3)
liquid (~> 3.0)
mercenary (~> 0.3.3)
rouge (~> 1.7)
safe_yaml (~> 1.0)
jekyll-sass-converter (1.3.0)
sass (~> 3.2)
jekyll-watch (1.3.0)
listen (~> 3.0)
jekyll_pages_api (0.1.5)
htmlentities (~> 4.3)
jekyll (>= 2.0, < 4.0)
jekyll_pages_api_search (0.3.0)
jekyll_pages_api (~> 0.1.4)
sass (~> 3.4)
therubyracer (~> 0.12.2)
kramdown (1.9.0)
libv8 (
liquid (3.0.6)
listen (3.0.3)
rb-fsevent (>= 0.9.3)
rb-inotify (>= 0.9)
mercenary (0.3.5)
rb-fsevent (0.9.6)
rb-inotify (0.9.5)
ffi (>= 0.5.0)
redcarpet (3.3.3)
ref (2.0.0)
rouge (1.10.1)
safe_yaml (1.0.4)
sass (3.4.19)
therubyracer (0.12.2)
libv8 (~>


@@ -0,0 +1,32 @@
As a work of the United States Government, this project is in the
public domain within the United States.

Additionally, we waive copyright and related rights in the work
worldwide through the CC0 1.0 Universal public domain dedication.

## CC0 1.0 Universal Summary

This is a human-readable summary of the
[Legal Code (read the full text)](

### No Copyright

The person who associated a work with this deed has dedicated the work to
the public domain by waiving all of his or her rights to the work worldwide
under copyright law, including all related and neighboring rights, to the
extent allowed by law.

You can copy, modify, distribute and perform the work, even for commercial
purposes, all without asking permission.

### Other Information

In no way are the patent or trademark rights of any person affected by CC0,
nor are the rights that other persons may have in the work or in how the
work is used, such as publicity or privacy rights.

Unless expressly stated otherwise, the person who associated a work with
this deed makes no warranties about the work, and disclaims liability for
all uses of the work, to the fullest extent permitted by applicable law.
When using or citing the work, you should not imply endorsement by the
author or the affirmer.
@@ -0,0 +1,90 @@
## 18F Guides Template

This is a skeleton repo containing the
[Jekyll]( template for
[18F Guides](

### Getting started

#### Installing Ruby

You will need [Ruby]( ( > version 2.1.5 ). To check
whether it's already installed on a UNIX-like system, open up a terminal
window (e.g. Terminal on OS X) and type `ruby -v` at the command prompt. For
example, you should see something similar to the following:

$ ruby -v
ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-darwin14]

If the version number is less than 2.1.5, or instead you see something like:

$ ruby -v
-bash: ruby: command not found

Then Ruby is not installed, and you should choose one of the installation
methods below. [The "Installing Ruby" page of the official
Ruby language web
site]( explains how
to do this in a number of ways across many different systems.

##### Quickest Ruby install/upgrade for OS X

On OS X, you can use [Homebrew]( to install Ruby in
`/usr/local/bin`, which may require you to update your `$PATH` environment

$ brew update
$ brew install ruby

##### Optional: using a version manager

Whether or not Ruby is already installed, we strongly recommend using a Ruby
version manager such as [rbenv]( or
[rvm]( to help ensure that Ruby version upgrades don't mean
all your [gems]( will need to be rebuilt.

#### Cloning and serving the Guides Template locally

To create a new guide and serve it locally, where `MY-NEW-GUIDE` is the name
of your new repository:

$ git clone MY-NEW-GUIDE
$ ./go serve

The `./go` script will check that your Ruby version is supported, install the
[Bundler gem]( if it is not yet installed, install all the
gems needed by the template, and launch a running instance on

#### Follow the template instructions

The Guides Template (either [running locally](http://localhost:4000) or the
[published version]( will walk you
through the rest of the steps to edit and publish your guide.

### Staging version (for 18F team members)

In addition to the `18f-pages` branch, you can create an `18f-pages-staging`
branch and changes to that branch will be published to
``, which is identical to
`` but provides authenticated access.

### Public domain

This project is in the worldwide [public domain]( As stated in [CONTRIBUTING](

> This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](
> All contributions to this project will be released under the CC0
>dedication. By submitting a pull request, you are agreeing to comply
>with this waiver of copyright interest.
@@ -0,0 +1,128 @@
markdown: redcarpet
name: 18F Plain language tutorial
- Gemfile
- Gemfile.lock
- go
- vendor

permalink: pretty
highlighter: rouge
incremental: true

style: :compressed

# Author/Organization info to be displayed in the templates
name: 18F

# Point the logo URL at a file in your repo or hosted elsewhere by your organization
logourl: /assets/img/18f-logo.png
logoalt: 18F logo

# To expand all navigation bar entries by default, set this property to true:
expand_nav: true

# Navigation
# List links that should appear in the site sidebar here
- text: Welcome
internal: true
- text: Tutorial goals
url: tutorial-goals/
internal: true
- text: Introduction
url: introduction/
internal: true
- text: What is plain language?
url: what-is-plain-language/
internal: true
- text: Why is plain language important?
url: why-is-plain-language-important/
internal: true
- text: Legal considerations of plain language
url: legal-considerations/
internal: true
- text: "Strategies: How to write in plain language"
url: strategies/
internal: true
- text: "Strategy 1: Always think of your user"
url: strategy-1/
internal: true
- text: "Strategy 2: Use the simplest word that will do"
url: strategy-2/
internal: true
- text: "Strategy 3: Keep it short and sweet"
url: strategy-3/
internal: true
- text: "Strategy 4: Cut to the chase (also known as the inverted pyramid structure)"
url: strategy-4/
internal: true
- text: "Strategy 5: Use visuals"
url: strategy-5/
internal: true
- text: "Strategy 6: If it’s broke, fix it"
url: strategy-6/
internal: true
- text: How can I tell if my content is in plain language?
url: how-can-i-tell/
internal: true
- text: Test your knowledge!
url: test-your-knowledge/
internal: true
- text: "Activity 1: Privacy statement"
url: privacy-statement/
internal: true
- text: "Activity 2: FAQs"
url: faqs/
internal: true
- text: There’s more to learn (additional resources)
url: more-to-learn/
internal: true

- name: 18F plain language tutorial
description: Main repository

url: ""
text: Return to 18F Edu

google_analytics_ua: UA-48605964-19

output: true
permalink: /:path/

- scope:
path: ""
layout: "guides_style_18f_default"

# Configuration for jekyll_pages_api_search plugin gem.
# Uncomment this to speed up site generation while developing.
#skip_index: true

# Each member of `index_fields` should correspond to a field generated by
# the jekyll_pages_api. It can hold an optional `boost` member as a signal
# to Lunr.js to weight the field more highly (default is 1).
boost: 10
boost: 10
boost: 5
Oops, something went wrong.

0 comments on commit 0bb28ca

Please sign in to comment.