Publishing a blog post

Purpose of the blog

The purpose of our innovation design blog is to share our user-centered design and development process at the Office of Natural Resources Revenue. The strategic purpose of the blog is to:

• provide a venue for long-form publishing about our process, decision making, and workflow
• nurture and support the adoption of our process, or elements of our process, in other federal agencies
• create another outreach vehicle for Natural Resources Revenue Data (NRRD)
• introduce a tool for Information and Data Management team collaboration and sharing
• continue telling the story of the NRRD site, started on 18F's blog in 2014

Development environment

Our blog is built with the open source site generator GatsbyJS. We built the blog in Gatsby as we simultaneously migrate the NRRD codebase from Jekyll to Gatsby.

The blog is published on the same domain as NRRD (revenuedata.doi.gov/blog), and we manage the workflow for it in the same GitHub repository (github/onrr/doi-extractives-data). The blog is in a directory called blog-site. We manage the workflow in this folder of the NRRD repository; Federalist builds the site and serves it at revenuedata.doi.gov/blog.

Workflow

There are two aspects of our blog workflow:

1. Editorial: the process of conceiving post ideas, applying editorial guidelines, reviewing and approving posts for publication, and strategic scheduling
2. Publishing: the technical process of drafting and publishing a blog post

We'll cover each aspect of the workflow step by step below.

Roles

Editorial

• Managing editor: Ryan Johnson, content strategist at the Office of Natural Resources Revenue
• Product owner and chief editor: Jennifer Malcolm, product manager at the Office of Natural Resources Revenue

Authors

• Authors: the entire Information and Data Management team is welcome to submit ideas for blog posts and author them, with approval and support from the editorial team. The editorial team encourages the submission of topics from any and all Information and Data Management team members.

Steps

Step 1: clone the repository (publishing, optional)

This is an optional step for authors who want to manage most of the publication workflow on their own, as opposed to being dependent on the editorial team to format their post.

This step requires git. Git can be installed on its own or by installing GitHub Desktop.

Most of the team already has git, as it's required software to work on NRRD. If you don't have git or GitHub Desktop, it may take time for IT to approve and install it. Work that into your sprint and publication timeline. You'll also want to set up a GitHub profile and request to be added to the ONRR GitHub organization.

Once you have git and/or GitHub Desktop installed, you can clone the blog repository using this command in the command line interface (Terminal on macOS; PowerShell on Windows):

git -c http.sslVerify=false clone https://github.com/ONRR/doi-extractives-data.git

You can also use the "Clone or download" button in GitHub.

Step 2: content calendar (editorial)

Our team maintains a content calendar (limited access) for the purpose of planning and coordinating data and content publication, social media, press releases, and other outreach efforts. The first step in the workflow is to review this content calendar for opportunities to coordinate blog posts with other team activities or opportunities.

For instance, if we're planning to publish disbursements data in late December, we can add the task of authoring a blog post about disbursements user research to the previous sprint. The post will be ready to publish when we publish the data.

Step 3: add blog posts to sprints (editorial)

We work in two-week sprints, so we should refer to the content calendar and create issues that we can add to sprints. We can assign authors in GitHub to those issues. Since the blog is in the same repository as the site, we can apple our existing sprint workflow and tools (e.g. Waffle) to manage the publication of blog posts.

Step 4: use Google Docs to write blog post (editorial, publishing)

In a perfect world, we would use one software tool to draft, review, and publish a blog post. Unfortunately, we don't have a single tool that fulfills all of the requirements of our workflow.

We'll use Google Docs to write our draft blog posts, for these reasons:

• provides a real-time, collaborative environment for writing, editing, and commenting
• our whole team has default access to Google Docs, so we don't need to work with IT to install new software
• tracks revisions, so we can easily revert to a previous version
• can export to multiple formats, some of which are relatively easy to convert to markdown (more on markdown later)

When setting up the Google Doc, the author should share the doc with coauthors (if multiple authors) and the editorial team.

Formatting a post: The author(s) can choose to format the post using default features in Google Docs (e.g. headings, bullets, links, styling), or format the post using markdown. The post will eventually need to be converted to markdown, either manually or by using a tool such as pandoc. There are advantages to each approach. If you use the default Google Docs formatting (instead of markdown), build time into the publication process to convert the document to markdown.

Refer to content guide: While writing – or following the completion of a first draft – authors should refer to the NRRD content guide for guidance on punctuation, capitalization, and vocabulary, among other things. We'll use the NRRD content guide for the blog as well, and we'll determine if we need a custom guide for the blog as we use this workflow.

Step 5: update the GitHub issue (editorial, publication)

When the draft post is complete in Google Docs, the author(s) should update the GitHub issue (in the doi-extractives-data repository) with the status and request a review by the editorial team (Ryan and Jennifer).

My [draft blog post on accessible web content](#) (limited access) is finished! Please review it, @jennmalcolm and @brentryanjohnson.

Cool. Remember to mark Google Docs as "limited access," since outside observers will not be able to access it because of the Department of the Interior's restrictions.

Step 6: edit and iterate (editorial)

The review process is a collaborative effort between the editorial team and the author(s). The process may be real-time coworking or independent commenting and iteration.

The duration of the review-and-iterate process will depend on the post subject matter, the length and complexity of the content, and the availability of team members. Ideally, the process is complete within a given a two-week sprint. Regardless of duration, the process should result in a final version approved for publication.

Step 7: convert to markdown and publish (publishing)

To start, you should create a new git branch on your local machine. Branch off dev and name the branch something descriptive, such as blog-homepage-redesign. Start the branch name with the word 'blog' so we know it's a post just by looking at the blog name.

If the post is already formatted with markdown

Preparing the post for publication is dependent on the format of the original Google Doc. If the Google Doc content is formatted in markdown, this may simply require copying and pasting the content into a plain-text file in the cloned version of the repository. Since our blog uses clean URLs, a new directory will need to be created in the pages directory. A sample file path for a blog post may be something like this:

doi-extractives-data-->blog-site-->src-->pages-->my-awesome-blog-post-->index.md

Even if the post was formatted markdown to start, images will need to be moved into the same directory as the markdown file. To include an image, move it into the same directory as the post (in this case, my-awesome-blog-post) and reference it in markdown:

![Text describing my awesome image for screenreaders](./my-awesome-image-name.jpg)

Double-check the formatting of the content. Pay particular attention to bullet styling, if used. If Google Docs converted markdown bullets to Google Docs bullets, you'll need to convert them back to markdown.

If the post needs to be converted to markdown

If the post is formatted in Google Docs, you have a few options:

• Ask someone on the team to convert it to markdown and prepare it for publication
• Manually reformat to markdown yourself
• Use a tool like pandoc to convert it, then audit the formatting for fidelity to the original structure (if you need help installing and/or using pandoc, request help from the editorial team)

If you're not comfortable writing in or converting the formatting to markdown, the editorial team will help you prepare the post for publication.

Step 8: add front matter (editorial, publishing)

In our publishing environment, blog posts must be in markdown format with appropriate front matter. Front matter refers to metadata at the top of the blog post that defines custom variables. For example, our blog template front matter defines the blog title, author(s), an excerpt, the date of publication, and tags. Front matter is set apart from the rest of the post with three dashes:

---
title: A great blog post!
authors: 
- Ryan Johnson
- Jennifer Malcolm
excerpt: This is an example, testing the excerpt in front matter.
date: "2018-10-03"
tags:
- test
- example
---

If you haven't authored a blog post for this site before, you'll also need to be added to the author.yml file. This file is located in blog-site-->src-->data-->author.yml. It includes three lines:

• id (your name, written the same way as you'll use in the post front matter)
• 'bio' (use the same format as the others listed)
• 'pic' (the path to your profile photo, which needs to be cropped to a circle and sized to 104px by 104px)

- id: Ryan Johnson
  bio: content strategist at the Office of Natural Resources Revenue
  pic: /img/ryan-pic.jpg

- id: Jennifer Malcolm
  bio: product manager at the Office of Natural Resources Revenue
  pic: /img/jennifer-pic.jpg

You, or the editorial team, will need to add your properly formatted profile photo to this directory: blog-site-->static-->img

The blog software uses the id to map to the list of authors in the front matter, and it automatically pulls the other fields into the blog post template.

About the excerpt

Keep your excerpt short but informative. It should be no longer than a paragraph. The excerpt is displayed with the blog title and date on the homepage.

---

The editorial team will complete the following steps.

Step 9: publish, part 1 (publishing)

Since we're managing the blog in the NRRD repository, we will release new posts when we release NRRD site versions (usually every two weeks).

If you want to preview your blog post on your computer, you will need to install GatsbyJS (if you haven't already). You will also need to install node.js, which should include npm.

To preview your post, make sure you're in the NRRD repository on your computer and run the following commands in Powershell (or another command line tool):

• cd blog-site (changes directory to the blog)
• npm install (installs the necessary software dependencies for the site)
• gatsby develop (builds the site and launches a local server with the built site)
• Go to localhost:8000 in your browser

You should see the site, with your shiny new blog post listed! Proof read your post and make sure the images are loading in properly.

Step 10: publish, part 2 (publishing)

Once your blog post is ready to go, you can commit the post to your branch and push the branch to the remote repository:

• git add blog-branch-name (Stages the post to prepare the commit)
• git commit -m "Adds blog post on our homepage redesign"
• git push origin blog-branch-name

Then you can open a pull request in GitHub and flag @jennmalcolm and @brentryanjohnson to review

Step 11: relax and revel in your blog skills

You've done it! Now you can relax, pet a dog, go for a walk, or start another blog post!

A few notes:

• To make it easier to start your blog post in markdown, you can copy and paste an existing post directory and edit the name and contents.
• A previous version of this documentation assumed the blog workflow would be managed in a different repository. This documentation (12/3/18) updates that workflow.
• The blog is a work in progress. We will continue to tweak the styling and layout as we go along.