Guide to supporting 18F guides

The principles that inform each and every Guide

Guides content vision statement

Origin document (18F only 🔒)

Long version

“Our Guides equip government staff with tools and practices to improve public services. They affirm experiences, build confidence, and empower staff to deliver better technology.”

Short version

“Our Guides equip staff with tools and practices to improve government technology.”

Guides design principles

Origin document (18F only 🔒)

These principles are intended to help the 18F Guides + Methods team, product owners, and content contributors make design, content, and development decisions. Reviewing these should help you get started.

Reflect 18F

The 18F Guides + Methods are how 18F shows up in the world — an opportunity to practice what we coach in terms of the processes we use, the content we share, and implementation approaches we choose. They must be a reflection of our values and the current state of our practices.

How we do this:

• Follow the recommendations made in our guides; for example, write in plain language, use the USWDS, ensure accessibility, set up automated testing, and observe other content, design, and engineering guidance
• Ensure the decisions we make about how and what to publish are in line with our best practices and values by coordinating with 18F SMEs regularly

Ask yourself:

• What would we tell others in this situation?
• Do the guides reflect what 18F stands for?
• Do you feel confident when sharing the guides?

Keep it current

The 18F Guides + Methods must be kept up to date. Visitors should feel confident that what is in the 18F Guides + Methods reflects the current state of 18F’s practices and organizational learnings — including how we’re incorporating emerging practices.

How we do this:

• Identify clear owners for all content so it’s clear who is responsible
• Consider the longevity of content before publishing
• Establish organizational evolution and governance processes to enable our learnings to be funneled back into the Guides
• Be clear about the maturity of different practices described in our guide
• Test new designs and workflow changes with content creators to make sure guides are easy to update

Ask yourself:

• How frequently should this be updated?
• Do we have the resources to keep this information up to date?
• Does this technology choice or process make it easier to make updates?

Prioritize the practical

18F puts the theory of technology best practices into action in government, so the 18F Guides + Methods should lead with the how and back that up with the why. After reading, visitors should clearly understand how to implement our practices.

How we do this:

• Call out practical resources like templates, checklists, references, and other applicable tools
• Leave out theoretical and background information — think about what is going to be useful to implementation by putting the how before the why
• Make it easy to navigate between related topics
• Avoid linking to documents with restricted access

Ask yourself:

• Can a visitor walk away with actions using what’s provided on this page?
• Is it easy to identify what information is intended to be applied rather than simply provided as background?

Focus on new 18F colleagues

By designing and writing for teammates joining 18F, we can serve the needs of our many audiences, including our partners, the broader civic tech community, and existing 18F staff, possibly those learning about other disciplines or emerging practices. Visitors should feel welcomed into a community of people trying to build great technology in government.

How we do this:

• Write with a welcoming, approachable, supportive, and clear tone
• Assume an intelligent, capable audience; do not oversimplify or condescend
• Solicit feedback from new 18F staff regularly

Ask yourself:

• How would someone new to 18F understand this information?
• What context is needed in order to make sense of this information?

Underscore government context

Government-specific information and examples set the 18F Guides + Methods apart and build trust with our partners. Some visitors will use the Guides specifically to understand how our work practices are affected by our government environment, and all visitors should be able to understand how and why we have adapted them.

How we do this:

• Highlight where practices differ in government compared to private industry
• Reinforce government context through requirements and considerations that are specific to government (for example, the Paperwork Reduction Act, Section 508 of the Rehabilitation Act)
• Link to examples from 18F and other public government sites rather than private sector resources — this is also a requirement to avoid being interpreted as an endorsement

Ask yourself:

• If taken out of context, would the visitor know that this information is focused on government practices?
• Are there any particular considerations that differentiate the way our work is done in government?

Who is responsible for what

(Please note that this is a recommendation that has not been fully discussed and implemented.)

The Guides ecosystem will be led by the Guides team, who will be responsible for identifying gaps and redundancies in the Guides.

[PERSON LEADING GUIDES TEAM] is responsible for final decisions regarding major updates, information architecture changes, and strategic direction for the Guides and Methods.

[Acq director] is responsible for assigning people to update and maintain the Derisking Guide.

[Design director] is responsible for assigning people to update and maintain the UX Guide, the Methods, and the Content Guide.

[UX supervisor] is responsible for day-to-day maintenance of the UX Guide. [UX supervisor] is responsible for day-to-day maintenance of Methods. [Content supervisor] is responsible for day-to-day maintenance of the Content Guide.

[Engineering director] is responsible for assigning people to update and maintain the Accessibility guide, the Engineering Practices Guide and the Engineering Hiring Guide.

[Engineering supervisor] is responsible for day-to-day maintenance of the Accessibility Guide. [Engineering supervisor] is responsible for day-to-day maintenance of the Engineering Hiring Guide. [Engineering supervisor] is responsible for day-to-day maintenance of the Engineering Practices Guide.

[Product director] is responsible for assigning people to update and maintain the Product Guide.

[Product supervisor] is responsible for day-to-day maintenance of the Product Guide.

How we determine when changes need to be made

Each guide will undergo a yearly [?] review in order to understand if content needs to be updated, otherwise changed, or retired. This review will take into account the 18F Guides site index; reviewers should check previous decisions and notes in order to prioritize and plan for needed changes.