humanutility / humanutility.github.io

Where we give a voice to the people government left behind.

Humanutility Blog

This repository contains the blog for the Human Utility project! It runs on GitHub Pages using Jekyll.

Getting the site

1. Make sure that you have Git installed and configured.
2. Clone this repository to your computer.

Starting the site

If you're using a Mac or Linux, go to the terminal and run:

script/server

If you're using a Windows machine, go the command prompt and run:

jekyll serve --watch

In both cases, you can open a new browser and head to http://0.0.0.0:4000 to see the site ✨ live ✨.

Writing posts

New posts are written in Markdown. To add a new post, create a new file under the posts/ folder. It should start with a date in the format of YYYY-MM-DD-, followed by any title you want.

Each post needs to start with some frontmatter, which is sort of like metadata describing the post. Each post should have the following keys:

• title, which is the title of the post
• permalink, which is the URL link. Typically this is the person's name being highlighted.
• description, which is a short description of the person being highlighted.
• image, which is an image of the person being highlighted.

For example, this might look like this:

---
title: Meet Loria—The First Person The Human Utility Ever Helped
permalink: /loria-detroit/
description: Meet Loria. The first person in Detroit The Human Utility ever helped with a water bill.
image: https://www.dropbox.com/s/k2i3ivenw1uobxi/loria.jpeg?dl=1
---

These metadata keys (image, title, etc.) are important, because they are used by the jekyll-seo-tag plugin to create cards for Twitter and Facebook.

Publishing posts

Any post merged into gh-pages will automatically go live on the internet!

Technical details

Plugins used

The following plugins are used to help make the site:

• jekyll-feed
• jekyll-sitemap
• jekyll-seo-tag
• jemoji

TODO

• Fix header and footer so that they match the rest of the website
• A lot of the SCSS styles were just stolen from Stripe. The files in the _sass/ folder should be reviewed to make sure they're actually being used.
• There should probably be shared on Twitter/Facebook buttons.

humanutility.github.io's Issues

Define a content strategy

The whole idea of a content strategy blew my mind when I first learned about it. Without a content strategy, each post is a unique snowflake that you have to invent from scratch. With a content strategy you define high level categories of similar content, and it becomes much easier to come up with ideas within a category.

Tiffani mentioned a bunch of different types of content that is relevant already. This could be a place to start writing these down.

E.g. the human stories behind the bills that get paid, how policy affects things, interacting with government, interacting with the utility companies, ...

Also, for each idea for a blog post or story, it could be worth considering what larger category of content this story belongs to, as that might represent a whole new rich stream of ideas.

Document process for publishing a post

The people publishing to the blog post are not necessarily going to be technical.

We need a README that documents in detail how to go about publishing a blog post.

This should likely be in two steps:

1. How to set the project up locally so you can write posts
2. How to actually write a post (and what the process is for it to end up on the blog)

For the second we'll likely need to explain how to:

• generate the file / where to look for it
• define the necessary metadata
• use markdown
• check it locally in the browser
• commit your changes
• submit a pull request

Design and implement blog

Someone recently characterized the Human Utility project as "a button that takes my money", which is a tragically incomplete characterization of the project. The purpose of the blog is to help bring a richer context and understanding of what the project is accomplishing, and how it is doing it.

People understand data, but they believe stories. —Mike Hoye

As a starting point, we will need:

• a simple, attractive, usable design
• separate template types for different types of content (probably depends on the content strategy, but at the very least, a "short post", a "long post", and a "profile", I think)
• content strategy (#3)
• content workflow (#4)
• sign up form for the newsletter
• documentation (#2)

Note: We can edit and update this issue to help organize the work on this project.

Define a content workflow

This doesn't need to be very elaborate, but it would be helpful to define:

• where to write down blog post ideas
• how to go from idea to published post