Our editing process is ever so slightly technical so that we can avoid using too many different types of documents and transplanting content from one format to another. By editing and writing directly in Markdown files, everybody is on the same page and speaking the same language.

Marking Up Edits

Much of our writing relies on elements like blockquotes, pull quotes, figures, code samples, and other rich content. This enables us to write directly in markdown with bits of traditional markup sprinkled in as necessary. Since we write directly in markdown and markup, it only makes sense to edit directly in markdown markup to help preview the impact to the content.

This process is a bit more tedious than tracking changes in Pages or Word, but it makes it easier to both review the edits and minimize the possibility of errors when moving the content from one medium to another.

Flag the Page

All of our pages allow us to specify body classes via the frontmatter YAML. In order for the page to pick up editing styles, just add the edited class to the body_classes YAML.

Deletions & Additions

Use del and ins to flag deleted and added content respectively.

ex. Here’s a deleted bit along with an inserted bit.

Notes

Use mark to add inline notes. It’s not the exactly correct markup to use, but in this context, it does the trick and works nicely with the stylesheets and markdown.

ex. I like monkeys. They are pretty. This sentence could be better. But I don’t like noisy monkeys.

Git Workflow

The best way to manage this workflow is to set up the repository locally and run Jekyll. This will make it easy to preview the result, especially when a given page isn’t publicly available from the site yet.

  1. Create a branch. In the case of new pages, a branch will already exist, and you’ll just need to grab that branch. With edits to existing pages, though, you’ll need to set up the branch. Branches make it easy to spread edits over a week without worrying about blocking any other updates. Branches can correspond to a batch of edits or a single page. The only standard to follow is to begin the branch name with edits-. ex. edits-quality-page. This way, if there are multiple edit branches, they’ll be grouped together.
  2. Make the edits. This can be done locally or directly from the GitHub site by editing the file and committing the changes there. While including multiple page edits in a single branch is ok, it’s important to keep the changes to a manageable amount because the pull requests will merge all changes from that branch. More edits means more time to discuss the pull request and a longer time before the edits can go live.
  3. Create a pull request. Once the edits are complete, create a pull request from the working branch onto master. Pull requests make it easy to have asynchronous conversations about edits and make it clean and simple to merge the edits.

That’s it. Then just sit back and wait for the pull request conversation. More often than not, there won’t be anything to discuss. We can just merge the edits and make them live.