-
Notifications
You must be signed in to change notification settings - Fork 4
Publishing a blog post (a to z)
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
Our blog is built with the open source site generator GatsbyJS.
The blog is published on the domain https://blog-nrrd.doi.gov, and we manage the workflow for it in a distinct GitHub repository.
To help track the work that goes into writing and publishing a blog, use the "Outreach" label for all Github issues related to blog posts.
- The entire Information and Data Management team is welcome to submit ideas for blog posts and author them, with support from other team members and final review by the product manager at the Office of Natural Resources Revenue. When creating the initial blog post issue in Github, use the label "Blog ideas."
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/blog-nrrd.git
You can also use the "Clone or download" button in GitHub.
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.
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 to manage the publication of blog posts.
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 use shared documents 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 them 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 document, the author should share the doc with the coauthors and reviewers.
Formatting a post: The author(s) can choose to format the post as text (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 text 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.
When the draft post is complete in the document, the author(s) should update the GitHub issue (in the blog-nrrd repository) with the status and request a review by the by the team as appropriate.
The review process is a collaborative effort between the author and the team. 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.
Checklist for editors:
- Check for typos, spelling, and grammar. Track changes in the shared doc and allow the author to accept your suggested changes.
- Put the post into Hemingway to check reading level. If it's above grade 10, make a note and suggest simplifications.
- Are paragraphs too long, or sentences overly complex? If so, offer simplifications to reduce the text's cognitive load.
- Offer suggestions to swap out common modifiers (great, very, really, etc.).
- Confirm the post follows the NRRD Content Style Guide.
- Confirm that images all make sense in context and add value to the text.
- Confirm the source file is available for any images to prevent a loss in resolution.
- Confirm header levels are used correctly.
- Check if there are other blog posts would add value to readers of this post and offer links to those posts.
- Are products referenced that ONRR should not endorse? If so, offer removal and explain your reasoning to the author.
- Check that all content that should be attributed to a person or group is, and offer attribution if needed.
- Finally, comment on the GitHub issue to let the author know you made edits and notes in the shared document.
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.
Preparing the post for publication is dependent on the format of the original document. If the document 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:
onrr-->blog-nrrd-->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:
Double-check the formatting of the content. Pay particular attention to bullet styling, if used.
If the post is formatted as text, 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 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.
After the blog post has been converted to markdown, confirm the following:
- Pictures are clear and not blurry
- Alt text is clear and concise
- The post contains no typos, grammatical or spelling errors
- All links are operational
- Headings and text style are used in accordance with the NRRD Content Style Guide
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-nrrd-->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
104pxby104px)
- 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 team, will need to add your properly formatted profile photo to this directory: blog-nrrd-->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.
- The excerpt is displayed with the blog title and date on the homepage.
- The excerpt should be short, informative, and consider different types of readers.
- The excerpt should be no longer than a paragraph.
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 Blog repository on your computer and run the following commands in Powershell (or another command line tool):
-
cd blog-nrrd(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:8000in 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.
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 team members to review
Once you can see your blog built you will be able to preview it in the final format through a preview link in your pull request. Now you can review to make sure that you properly formatted your markdown file.
- Ensure that all of the images show up and the links are directed to the right destination
- Run the site through a tool like Hemingway to check for that the blog is written to no higher than a 10th grade level.
- Check again for proper grammar and punctuation.
- Have your colleagues review as well and make all changes before asking the product manager to review.
Once your colleagues and product manager approve your pull request, the pull request will be merged into dev by the product manager. The blog will be posted with the next site release. Cheers!
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.
- The blog is a work in progress. We will continue to tweak the styling and layout as we go along.
After publishing a blog post, it is important for the author(s) and team members to distribute the new blog post to different communication mediums. You can use checklist to guide the distribution, but all checklist items are optional.
- Email digital.gov listervs or other listervs with short introduction and blog post link.
Consider posting to the following digital.gov listservs:
- User Experience
- Web Analytics
- Web Managers
- Post to LinkedIn or other social media accounts.
- Personal accounts
- ONRR accounts, which require communications specialist approval and posting
- Explore and reach out to blog digests to reach a larger audience in public and private sector.
- Email contacts who have expressed interest in a particular blog subject.
Relevant contacts may include:
- People who have given feedback on previous blog posts about a topic.
- People who have requested help from our team related to digital experience, content strategy, product development, etc.