The most important advice I give 18F staff while they’re working on a blog post is to define their audience as clearly and as narrowly as possible. This focus has helped us overcome numerous hurdles to publishing quality blog posts, and it’s also the part of our new 18F Blogging Guide that I’m most excited about.
We use a private GitHub repository to manage our blog editing and approval process. Blog posts enter as an issue in the “idea” milestone and exit as a closed issue in the “approved” milestone after they’ve been edited by a member of our blog team and sent through our approval process.
An example of an issue for a blog post.
Each issue has five metadata headings, including audience, that the author must fill out before the issue can move through our process. Here’s what our guide has to say about the importance of defining your audience:
It’s crucial to decide on your target audience before you start drafting a blog post. Being as specific as you can will help you answer a number of questions about what your post will look like. “General public” or “the federal government” is too broad of an audience to be useful. Clearly defining your audience will help you determine length, technical detail, tone, how much background you need to include, and what ask you will include at the end.
To help authors identify a narrow audience, we borrowed a technique from our developer colleagues: user stories. User stories are a single sentence that helps define a feature for a product by identifying a type of user, a feature that user wants, and why they want that feature.
We’ve modified the user story a bit to fit blog posts. Our template is:
As a type of audience, I want to learn something, so that some benefit is had.
An example of a good, clear audience story is something like:
“As a Chief Information Officer, I want to learn about the specifics of 18F’s new service, so that I can see if it will help me modernize my agency’s technology.”
We value a diverse set of voices on our blog, so we encourage everyone — developers, designers, product managers — at 18F to write for our blog. This means many of our authors are more comfortable writing Javascript than they are at writing narratives. Our staff is also very passionate about their work, so they’ve always got half a dozen ideas they want to put into a blog post. Writing audience stories helps make the writing process much less daunting and helps authors choose the one thing they most want to convey.
You can read the rest of our Blogging Guide to learn about how we use GitHub to manage our process and to see the other tips we give authors. We’re sharing this guide because our open source policy extends beyond our code, and because we think our editorial process can benefit from community input. We welcome issues and pull requests to the guide, and, as always, this guide is in the public domain so you are free to copy it and use it however you’d like.