Content editing checklist

About this checklist

This checklist provides an easy way to make sure that the way you write a method—no matter where it originates—is consistent with our style and the other methods. Use this when drafting new methods, when editing someone else’s work, or when submitting pull requests.

This will help us create a coherent design that users can scan quickly, no matter which method they’re looking at. And it will make the task of reconciling the digital and print versions a little easier, whether it's 18F staffers or people who want to print their own method cards at home.

Standard method pages

General

• Provide metadata at the top of the file in a format identical to the metadata from other methods. (Copy the formatting from any of the existing methods.)
• End all one-sentence (or one-fragment) descriptions with periods. (One hopes it goes without saying, but do the same for multiple-sentence descriptions.)
• Remove any stray characters leftover as markup from other programs. For example, if you copy from a Google Doc, you may find something that looks like [qq] at the end of a word or sentence. That indicates where an editor left a margin comment. Get rid of those!
• Talk directly to the user. Say “you” wherever it feels natural.
• Use curled quotation marks and apostrophes. You can use either “ and ” or (on a Mac) Option+[ and Option+Shift+[. For single quotes, use either ‘ and ’ or (on a Mac) Option+] and Option+Shift+].

Titling and other high-level information

• Make sure the method’s name, URL slug, and markdown file name all match.
• Put the name of the method in sentence case unless it is a proper noun (for example, a trademarked method we recommend).

What it is

• Start with a noun. Describe the concept of the activity, not how to do it. Put that information in How to do it.
• Keep to just one sentence fragment. The rest of the method provides plenty of room for more details.

Reasons to use it

• Start with To and go right into the main verb. Example: To stimulate stakeholder imaginations.
• If someone could understand why they might use the method after just one sentence fragment, leave it there. If you need to explain something that is still unclear, like why to use this method instead of another one, you can add one more sentence.

Time to conduct

• Designate the timeframe as small, medium, or large. In general, project times measured in minutes are small, in hours are medium, and in days are large.
• Write all lengths of time in numerals. (Any numbers elsewhere in the copy should follow standard style, where single-digit numbers are written out.)
• If you are listing the time as a range, use an en-dash and no spaces. En-dashes are either – or (on a Mac) Option+–.

How to do it

• How to do it and Applied in government, collectively, should be no more than 1,200 characters.
• Format all steps in an ordered list. Indent any sub-steps and use a simple hyphen and space. Example: - texthere
• List any work to gather materials or people as the first steps.
• If the card references the subject of any other method, hyperlink that text to the other card using the permalink from the linked card's metadata. It should be in double-dot notation, not the full-length URL. Example: [your hyperlinked text](../permalink/)

Applied in government

• Use dashes to create an unordered (bulleted) list if there are two or more points made. If not, no bullets at all.
• Format references to federal code like this: 5 CFR 1320.5(h)3.

Additional resources

• Delete this section entirely if you have no additional resources to list.
• Use dashes to create an unordered (bulleted) list if there are two or more points made. If only one, don't use bullets.
• Format naked URLs as if they are hyperlinked text. Do not rely on the browser to hyperlink for you. Put a ` on either side of the URL as text. This will prevent unusual formatting. Example: [`URL as text`](http://url.com)

Fundamentals pages

Some of what you’ll find in Methods are not actually design research methods. Instead, they describe work that government design researchers should do no matter which method(s) they’re using. Most of these also apply to design researchers outside government.

There is no standard template for fundamentals, but follow the guidelines under General above. 18F’s researchers review all edits to fundamentals before we publish.

Phase and category pages

To make navigation easier, We group the individual methods into four phases of the design process. Within each phase are categories of research.

• List any new methods on exactly one phase and under exactly one category.
• List methods within a given category in alphabetical order.
• Format category headers identically across all phase pages.
• Match the title of the method as listed to the title as it appears on that method’s page.
• Check that the URL for any new method actually resolves when you click a hyperlink from the phase page.