About the Foundation for Public Code

How and why we blog

Contents

  1. Why we have a blog
  2. Blogposts are ephemera
  3. Before you start
  4. Write your blogpost
  5. How to create a blogpost on the Foundation’s blog
    1. Step 1: create your branch and file
    2. Step 2: create your blog post
    3. Step 3: create a pull request and release the new blogpost
  6. Further reading

Contribute on GitHub

We blog for a number of different reasons. This guide gives background information about the blog and instructions on how to blog.

Why we have a blog

The blog is our primary tool for talking about:

  • our work: what we’re working on and what we’ve learned
  • our news: what we’ve achieved and what we’ll be doing next
  • our community: interviews with and guest posts by community members
  • our position on important issues: why we’ve made the political, technological, organizational or design decisions we have

Not all information published on the blog needs to support our marketing strategy - for example, an in-depth discussion about a technology choice we’ve made may not persuade potential Foundation for Public Code partners, but will be interesting to technologists in our community.

To make sure we have the editorial freedom to publish about all of our work (no matter how niche), there’s no direct link to the blog on publiccode.net. Instead, we may feature important blogposts. (We’ll build this functionality once we have important blogposts.)

Blogposts are ephemera

Blogposts are different from resources and guides published on About, which we keep updating. By contrast, a blogpost is only true at that moment in time. We shouldn’t ever update a blogpost with more current information.

Instead, we can add a note with a link to follow up blogposts or new information published on the same topic. Adding links from older blogposts to newer blogposts also lets new blogposts benefit from the greater search engine weighting given to older, still popular pages.

This approach reduces our future content debt and avoids undermining our position of authority - for example, we’ll never have to change a blogpost to say that due to a government policy shift, an expert we’ve interviewed is no longer in post (which might cast doubt on that expert’s still-relevant advice).

Before you start

  1. Since none of us work in isolation, check in with the communications coordinator before you start writing your blogpost. This helps us:
    • understand your goals and audience for the blogpost
    • establish the scope of your blogpost (to avoid duplication with other planned work)
    • schedule publication of your blogpost so it fits best with other planned communications
  2. Read our style guide - we use 18F’s. If you have any questions, ask!
  3. Make sure your information is correct in blog/_data/authors.yml.
  4. Read the guide on writing community call blogposts if that’s what you’re doing.

Write your blogpost

Write your draft blogpost using a collaborative document tool. This lets you share it for pair writing, factchecking, feedback or proofreading.

Don’t hesitate to involve other people in your writing process - we want you to succeed, and we know how helpful an external perspective can be once something starts to feel like a slog.

Include links to people, associations, codebases, organizations or events you talk about - this helps an excited reader learn more. It’s also useful for search engine optimization (SEO).

All blogposts should include at least one relevant image or video, to make them more engaging.

After writing, please share with the communications coordinator for polishing and to schedule publication.

How to create a blogpost on the Foundation’s blog

Step 1: create your branch and file

Create a branch for your new blogpost within in the blog repo.

Create a new file for your blogpost within _posts/ on the blog repository named YYYY-MM-DD-title.md.

Step 2: create your blog post

At the top of the file you should have this frontmatter:

---
title:  "Title"
date: YYYY-MM-DD
author: [put your name]
type: blogpost
excerpt: [unformatted text you want to appear on the index]
category: [our current categories are: news, codebase stewardship, community call and policy]
---

Note: your blogpost can only have one category.

Add your images to _assets/ on the blog repository. Link to the asset directly in text. Make sure the text alternative for your image is useful.

Example:

![alternative text]({{site.url}}/assets/image.jpg)

If you would like to link to another blogpost, use a dynamic link.

Example:

[Text you want to hyperlink]({% post_url yyyy-mm-dd-title-of-the-post-you-want-to-link %})

Step 3: create a pull request and release the new blogpost

Commit your changes and create a pull request. Tag the communications coordinator plus any other colleagues whose review you’d like on the pull request for your blogpost for a final proofread.

Once approved, your pull request will be merged. If the date in the frontmatter is the same as (or earlier than) the day the pull request was merged it will appear as published in the blog immediately. If the date in the frontmatter is in the future, the site will need to be rebuilt that day to make it visible. This can be done by entering the Actions tab on Github, clicking on the latest deploy to see the details and then clicking the “Re-run all jobs”.

Further reading