Content editing and publishing workflow - DOI-ONRR/nrrd GitHub Wiki

So you’re helping out with some content on Natural Resources Revenue Data (yep, that’s NRRD for short 🤓). Awesome! We’re grateful for your contributions.

Let’s get into it. Our team has two primary content leaders: our content strategist and our product manager. These two team members make the final decisions about content changes or additions. But don’t worry; they’re really nice and super collaborative.

Content on NRRD is managed (mostly) in 3 formats in our GitHub repository:

• Markdown (may include HTML and CSS)
• JSX
• YAML

I tried to warn you! We aren’t called NRRD for nuthin’. But don’t worry; it’s no big deal. Before we get into the details about how to manage content in these formats, let’s talk about when to manage content.

I feel for you. You just completed a content audit, and now you have a bunch of stuff to update, augment, or otherwise edit.

Or perhaps someone in leadership called and told you to add a photo of their cat to their bio.

Or maybe you just completed a usability testing session, and you found out the way you phrase something is completely different than the way your users phrase it.

Or maybe you’re building a new feature, and you simply need to draft new copy for it.

The point is, there are many, many reasons for changing and adding content (not the least of which is that content is a process). But you do need to find a way to manage how you approach content updates, so you don’t get overwhelmed.

I like to do an annual content audit (see above) to evaluate our stuff and make decisions about what to tackle first. If you’re super lucky, you’ll have nothing to update. But I’ll bet you’re not lucky.

It’s important to remember that your content is alive. Or rather, the perception of your content is alive. To understand this idea more fully, I suggest you read Stuart Chase’s The Tyranny of Words and Abby Covert’s How to Make Sense of Any Mess. I’ll wait. JK.

The point is, if you’re paying attention to current events, your users, and (especially) your content, you’ll know when to dig in.

Now for the fun part.

Before you change anything, be sure to review our content style guide. The guide helps with content consistency, and can also be useful for working with ambiguous words, phrases, and punctuation.

As I mentioned, our content lives in big, beautiful, coded houses. Or apartments. Or components. Whatever.

We manage content this way for no particular reason, other than we haven’t had time to build a proper content management system. But you know what: content management systems are a cheat. You’re a true content person. Someone who likes to build their content sculpture out of the raw material of the web.

To help us track our work in Github, when updating or adding content, add the "Content" label to your issue. Also add the "Enhancement or "Maintenance" label, based on the context of the changes being made.

And now, the materials we work with...

It’s the best. Markdown is very cool. You get to structure your content with the simplified, almost-raw-material of the web. It’s very exciting. Plus, it’s super portable. You can migrate content in markdown easily, and then build a new site around it (if you want).

I’m not going to teach you how to write in markdown…you can learn markdown here.

Much of our supporting content, such as that found in How it works and Downloads, is in markdown format. In the repo directory, you’ll find it at src-->markdown.

Most of the markdown filenames should be self-explanatory, and the landing pages for each section are (usually) named default.md. For example, if you want to edit the How it works landing page, you’ll find it at src-->markdown-->how-it-works-->default.md.

You'll probably want include a React component in your markdown from time to time. For example, you may want to define terms with NRRD's glossary feature.

The way we do this now is imperfect (but don't worry about that). We're looking at an alternative using MDX, but in the meantime, here's the format:

<glossary-term>bonus</glossary-term>

Simple, right? Which probably means there's a gotcha...

Developers seem to love JSX. Content managers...not so much.

Let's find out why...

const StateDisbursementsSummary = props => {
    const usStateDisbursements = FederalDisbursements(props.stateId,props.data);
    const stateName=props.stateName;
    const maxYear=usStateDisbursements.All.MaxYear
    const allDisbursements = (usStateDisbursements && usStateDisbursements.All.All) ? usStateDisbursements.All.All[maxYear] : 0
    
    return (
	    <div>
	    { allDisbursements > 0 && <p>Revenue from federal land resulted in <strong> {utils.formatToDollarInt(allDisbursements)}</strong> disbursed from the federal government to {stateName} in {maxYear}.</p> }

      { (allDisbursements == null || allDisbursements == 0 ) && <p>No disbursements were reported for {stateName} in {maxYear}, probably because there was no revenue from production on federal land.</p> }
	    </div>
  )
}

Oof.

JSX is cool because it allows you to add logic to your content. Your content is smart now. It's a powerful tool for content designers 💪.

I'm not going to lie: it can be difficult to find the content you need to edit in JSX. I advise you to simply search for part of the string of content you need to edit. For example, if you needed to edit something in the above JSX block, you could open the codebase in your text editor and search for it. In this case, I would search for a string that doesn't contain a data point, since that's likely plugged in with a variable ("Revenue from federal land resulted in"). If you have a decent text editor, it should narrow your search.

If you feel like unnecessarily torturing entertaining yourself, you can read this intro to JSX and look through src-->components in our repo to track down the relevant JSX among the React components.

YAML is silly. No, really! YAML stands for "YAML Ain't Markup Language." See?

But it's powerful silly stuff. You'll see it in the front matter of markdown files. It looks like this:

---
title: Gulf of Mexico Energy Security Act (GOMESA) | How It Works
layout: content
permalink: /how-it-works/gomesa/
tag:
- How it works
- Gulf of Mexico
- Federal laws
- Regulations
- GOMESA
- Land and Water Conservation Fund
- Revenue
- Disbursements
- Alabama
- Louisiana
- Mississippi
- Texas
---

This is how we add metadata to markdown files, and it allows you to do some cool stuff. For instance, we could use the tags to generate a page listing everything related to a particular subject, such as "GOMESA".

We also use YAML for some data files, including our glossary terms and definitions. Excavate it at src-->data-->terms.yml (at present, you'll see loads of other yml files here from previous versions of the site. Just ignore them.).

Here's a sample from the glossary terms data file:

- name: "8(g)"
  definition: "The 8(g) zone is the offshore region within three miles of a state shoreline. A portion (27%) of revenue from production in the 8(g) zone is distributed to the respective states that border the zone. The 8(g) zone is named for the section within the Outer Continental Shelf Lands Act that designates it."
- name: "Abandoned mine land fee"
  definition: "A fee for current day coal production that funds reclamation of mines abandoned before 1977."
- name: "Accounting year"
  definition: "This data is based on transactions that were reported to and accepted into ONRR’s financial system in a given a year. Since companies are allowed to adjust and correct data up to seven years after a transaction takes place, accounting year data can include corrections for sales that took place in previous years. This data is most useful when analyzing dollars ONRR collected and disbursed in a given year."

I think YAML is cool because it focuses on human readable serialized data. It's quite lovely, if you're a word nerd, but you're also...just a nerd.

Just as with markdown and JSX, I'm not going to teach you how to format YAML here. You can learn about YAML on this nerdy website. Spoiler: pay attention to your indents and quotes. For instance, since key-value data pairs in YAML are separated by a colon, you'll need to wrap your value in quotes if it contains a colon. Lost? Here's an example:

- name: A thing I'm defining
  definition: "This definition has a colon introducing more stuff: so I need to use quotes around it so YAML doesn't get 
  angry."

Git and GitHub are the foundation of our content publishing workflow, but I'm not going to go into detail about it here. Take a look at these guides:

• GitHub Guide
• Cloning a repository
• How to prepare and review pull requests

I'm going to focus on the review process here. Let's assume you're opening a pull request under the following circumstances.

Scenario 1: Let's say you've made content changes in markdown and they're relatively trivial. What do you do?

• Check the build status in CircleCI and Federalist (at the bottom of each pull request).
• Flag the content strategist and product manager for review, along with another subject matter expert (if you so choose).

Scenario 2: You've made changes to a section heading in JSX, and you're kinda 😱.

• Check the build status in CircleCI and Federalist (at the bottom of each pull request).
• Flag both the product manager and a developer for review. Remind the developer after a couple days.

Scenario 3: You've added a glossary term, and you feel 💪 but also a little 😳.

• Check the build status in CircleCI and Federalist (at the bottom of each pull request).
• Flag the product manager or content strategist for review.

It's all going to be okay. Because you're a content champion, and that makes you special. Keep at it 🙌.