Writing Lab 101

The Writing Lab team knows that writing is hard: It can be time consuming and stress inducing, and can sometimes seem like a blocker to a project that’s humming along. That's why the Writing Lab came into being. The Lab is a virtual writing center where you can get personalized help from members of the 18F editorial team. (And, if you’re a writerly type yourself, you can join the Lab team and volunteer to help other folks with their writing and editing projects!)

Leadership

The 18F Writing Lab is run by members of 18F’s editorial team, which includes members of the Content Guild, the Experience Design Content team (folks who work primarily on partner projects), and the Outreach team (folks who focus on internal and external 18F communication and evangelism).

All Lab members volunteer their services and base their contributions on their availability at a given time. When you file an issue or ask for help in Slack, one of the Writing Lab members will offer to help and assign themselves the issue you create.

The team’s collective experience is vast. Lab members hail from backgrounds in journalism, instructional design, creative writing, public media, and more. Whether you’re thinking about creating site copy or a conference presentation, someone from the Lab has the expertise to scrub in and help.

Frequently asked questions

What kind of help can the Writing Lab offer?

TL;DR If you have words and would like help, let us know!

The Lab is happy to offer you generative, developmental, stylistic, or copy editing help on any of the following types of writing:

• Final deliverables (recommendations documents, final reports, presentations decks)
• Mid-process artifacts (interview protocols, screeners, process documentation, research plans, statements of work)
• Playbooks and instructional materials
• Website content
• Blog post
• Talking points
• One sheets
• User interface copy
• Emails
• White papers
• Presentations or slide decks
• Partner agency communications
• Important or urgent news messages to be shared org-wide (such as Slack or email messages; we can usually turn these around in under 24 hours)
• Content strategy
• And more!

Our role is limited to improving the overall quality of content — its readability, flow, voice, and tone — and doesn't include approving it for publication. After a piece of writing has passed through the Writing Lab, it will be polished and will follow , external,18F’s Content Guide, but that doesn’t necessarily mean it’s ready to be published. Obtaining necessary approvals, designing a place for the content to live, and completing the technical work of posting content are all responsibilities of the content owner.

The Writing Lab is designed for short engagements. If you need more than 10 hours of content help, please visit , external,TTS-only, #staffing-resourcing to ask for guidance on getting somebody assigned to your project.

How do I ask for help?

You can post your request in , external,TTS-only, #18f-help-wanted, or , external,TTS-only, #tts-help-wanted if you are not in 18F.

What should I do if my issue isn't picked up?

Lab members assign themselves to issues as they can. Each core Lab member is cleared to spend three hours per week on the Lab, so our ability to pick up and close issues is based on the number of issues coming in and the workload of other projects.

If your issue isn’t assigned to someone within three days of you filing it, please ping the team in , external,TTS-only, #writing-lab or leave a comment on the issue. If your content has a hard deadline, please note that in the issue. Add the urgent label if it needs to be completed in the next two days.

How do I share feedback?

We’re always looking for ways to improve the Lab workflow, the quality of our services, and your experience as a customer. If you have any ideas or questions, please , external,complete our feedback survey or reach out to the team on Slack in , external,TTS-only, #writing-lab.

What has the Writing Lab worked on in the past?

Feel free to peruse the , external,TTS-only, issues associated with the Writing Lab repository. Also, if you haven’t had a chance to check out the , external,18F Content Guide yet, that’s a great place to go to familiarize yourself with our style.

Additional Resources

Here’s a list of the Lab staff’s favorite resources. Are we missing something? If so, add it to the list.

• , external,18F Content Guide: The official source for 18F’s content policies and preferences
• 18F Blogging Guide: Your guide to writing, editing, and publishing posts for the 18F blog
• , external,TTS-only, The Writing Lab’s performance profile guide: An informal guide for editing performance profiles

Guidelines for submitting an issue

Writing a good issue title

The best issue titles have three elements, in this order: team, content type, content name.

For example:

• Talent - Performance Profile - Front end dev
• Accessibility - Guide - Images section

Since this is all internal, feel free to use common shortening and abbreviations in your titles. Having this information helps members of the Lab pick issues that are right for them. Some of the Lab members have worked more with certain teams and are more familiar with their content and style.

Metadata

We ask all authors to submit a few pieces of metadata with their issue. This metadata helps us manage the Lab and complete your issue quickly. We’ve created an , external,TTS-only, issue template that you can use. For the project type section, you will pick one option from the list provided. For the help type section, explain what kind of help you're looking for. For the jargon and sensitivity sections, tell us what thinks we should be on the lookout for while we're editing.

Here are some additional guidelines to help you fill out the other sections of the issue.

Due date

If your content has a hard deadline, please list it in the issue.

Audience

Having a narrowly defined audience is probably the most important factor in having content that is easy to edit and easy to read. Knowing who is going to read this content helps Lab editors know what kind of tone and word choice is appropriate. Your audience should be distinct enough to help prioritize the most important content and exclude unnecessary information. Thus, descriptions like “general public” and “the federal government” are too broad. You can help define the audience and goal of your post by creating a , external,user story with this simple format:

As a type of audience , I want to read or learn something , so that some benefit is had.

If you’re writing about a new service that 18F is offering, your user story might be:

“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.”

This narrow focus will help you decide a number of things. Because your audience is federal technologists, you can assume a certain familiarity with government processes and terms. This allows you to go a little deeper into government procedure and some of the nitty-gritty of how this product works. You might also choose to use a slightly more formal tone for this post since this could be the opening message in a businesses conversation.

If you’re sending a staff-wide email to 18F, your user story might be:

_“As an 18F staff member, I want to know what our new README guidelines are, so that I can make sure my repo is up to date.”

Using this framework, you can be more informal since you’re writing to your colleagues, and you can use jargon that is known to the 18F team.

Bill to

If your Lab request is for a billable project, please list the Tock project name so that the Lab member who assists you can bill their time to your project. Again, if this is a major project that requires more than 10 hours of content work, please visit , external,TTS-only, #staffing-resourcing to ask for guidance on getting somebody assigned to your project.

If your request is for a non billable project, please also list the Tock project name. If there is no Tock project name associated with this piece of content, then the Lab will bill it to writing-lab in Tock.

Either way, the Lab member who assists you will provide you with regular billing updates so you can keep track of how much time they have spent on your issue and how that may affect your project budget.