18f/guides

18F’s guides equip 18F teams, our partners, other practitioners, lawmakers, and the public with tools and practices to improve public services. They affirm experiences, build confidence, and empower exceptional digital experiences.

18F Guides

18F’s guides equip 18F teams, our partners, other practitioners, lawmakers, and the public with tools and practices to improve public services. They affirm experiences, build confidence, and empower exceptional digital experiences.

Since 18F guides launched in 2015, they are:

• Referenced and replicated broadly. A review of traffic in 2022 found the guides were accessed more than 660,000 times across 217 countries, and guides have been printed, bound, and distributed within the United States Senate to help spread the word and make more data-driven decisions. This review found 454 GitHub forks across all the 18F Guides + Methods (our guides were previously maintained as separate products, and were consolidated in 2023).
• Widely cited and used, including in onboarding materials for organizations both public and private, as resources of best practices by programs like Digital.gov, and with 18F’s agency partners. Agency partners continually highlight that the guides inform new ways of working even outside of teams building software, like adopting retrospectives within new acquisiton process reviews. In one project, an agency partner highlighted the guides empowered staff to introduce and demonstrate the value of usability testing, which resulted in a 90% reduction in engineering rework on their product.
• Bettering delivery, within 18F and beyond. The 18F Guides help us do our work well and consistently. They are a resource to 18F staff for orienting and onboarding, reference, partner support, knowledge management, training, continuity, and more. These best practices are cultivated over time through our open source process and enable us to share and apply knowledge across projects, allowing incremental improvement as our experience grows. As our projects benefit from this knowledge sharing, so do our partners and the people they serve.
• Bringing new skilled technologists to government service. The guides are cited as the way that current employees discovered, became attracted to, and ultimately applied to 18F. A review of 18F staff departures in 2023 found that 85% of people leaving 18F exited for another government technology position.

I’d like to make a contribution, how do I update this content?

18F Guides aim to serve as the repository for best practices across 18F project teams. All team members are encouraged to suggest improvements that benefit the rest of the organization, particularly future new hires.

Though these guides carry the 18F brand, the intention is to spread the use and cultivation of the material throughout the broader digital services community. As new digital service teams launch across government and agencies and existing teams seek to improve their current practices, the guides provide a government-centered vehicle for knowledge sharing and skills acquisition. The guides complement the Digital Services Playbook by providing teams detailed, practical advice on how to implement the plays. Though these other teams are welcome to fork their own copies and maintain them, we hope the innovations these other teams develop will find their way into the guides, to the benefit of all government teams using them.

By developing this material in the open, we hope to encourage expert review and contributions from members of the tech community outside of government, furthering our goal of improving how government works through increased civic engagement of tech specialists. We hope this material and the means by which it is developed will attract new recruits to government technology positions, but for those who are not inclined to do so, helping cultivate the guides is a potentially high-visibility, high-impact contribution to government work that doesn’t require a major life change.

The CODEOWNERS file keeps track of who is in review & approver roles for content in the guides — if you’re not receiving a timely (within two weeks) review or notice the list is outdated, reach out to 18F’s Chief of Delivery for assistance. These reviewers will be automatically tagged appropriately when opening pull requests. Read CONTRIBUTING for more information.

Development

The re-platformed sites use 11ty. If you could run Jekyll, you should be able to run 11ty! There are two approaches to working with the guides: Local installation and Codespaces.

Ensure that you have the latest version of Node installed.

To run the site locally:

1. Clone this repo
2. From the repo directory, run:

   npm install
   npm run dev

3. Open http://localhost:8080

For more information on testing and repo configurations, read our in-depth development docs.

Codespaces

Codespaces allows you to set up a development environment easily and without dependencies on a local machine.

Start a GitHub Codespace

1. From this repo, Click "Code" and then the "Codespaces" tab.
2. Click the "+" icon, agree to the terms.
3. You should then see the repo interface. At the bottom, check the branch you are currently viewing or create a new one.

Start the application and preview the site

1. Give this a few minutes to warm up. At first, it will have a message "Welcome to Codespaces." If you wait a bit, you'll see it recognize the environment and start to install libraries for you.
2. Once it finishes installing the libraries, click on the "terminal" and type npm start.
3. It will think for 10 - 20 seconds and then you should see a message pop up on the right side that the site is available. Click "open in the browser.

Make changes, preview them

1. Select a file from the file explorer that you want to edit. Make some changes! You should be able to refresh the preview tab to see them immediately. If you will be making changes to styles, you will need to restart the server via npm run dev for those to be reflected.

Commit your changes

1. When you’re happy with how things look, switch on the left-hand menu to the "sourcecode" view. It will show you any changes you have made. Click the file name (on the left) to view things you've removed/added to that file.
2. This is a good time to create a new branch if you haven't already started on one! Click the three dots at the top of that menu, then "Branch" then "Create Branch". Give it a name like "design-update" or "cool-new-footer" and hit enter.
3. You will need to stage each file that you want to be committed. Once that's done, it's time to commit and push! You can click "commit" and then "publish" or you can use the arrow to select "commit & push".
4. On the lower right, it will ask you if you want to create a pull request. If it's too soon, don't click this. Otherwise, feel free!

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of

guides's Issues

SWOT analysis of Guides work

A description of the work

This is a follow-on to https://github.com/18F/TLC-crew/issues/486 and https://github.com/18F/TLC-crew/issues/479 (along with other context-gathering efforts).

In order help enable decision-making for the Guides going forward, it might be useful to create a SWOT analysis.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

2 days

Acceptance Criteria

• We have a completed, classic SWOT analysis matrix

Adjust default header from "Approaches" to "Guides"

Per @igorkorenfeld's comment in #84, the current default header for pages that are not part of a particular guide is "Approaches". We should change that default header to be "Guides" instead.

Acceptance criteria:

• When a user navigates to a page that is not part of a particular guide (such as a 404 page), the header will display [18F logo] "Guides"

Create tests for template logic

Work is currently being done to redirect pages and apply "nofollow" attributes to URLs via meta tags. The logic for this lives in liquid templates.

A small test suite that checked combinations of environment variables and URLs for the presence or absence of these meta tags would help us check that our logic is correct, reduce reliance on manual testing, and serve as guardrails for future changes as we add more guides.

If pursuing this, the task would likely need to be broken up into smaller issues. For example: identifying testing the library we want to use for testing, hooking it up in 11ty and adding it to CI, and creating tests for specific cases.

As a website visitor, when I navigate to a page that doesn't exist, I want to see a clear and user-friendly 404 error page so that I know the page is not available and I am able to easily navigate back to the main site

Acceptance Criteria:

• When a visitor tries to access a page that does not exist (i.e., there is no URL mapping to resource) they should be redirected to the 404 error page.
• The 404 page has a message that indicates the page does not exist.
• The page is consistent with the Guides and Methods/18F Branding
• The page includes a link back to the website's home page.

Migrate the Content guide to the new setup

🟢 CONTENT IS READY TO GO 🟢

A description of the work

We will migrate the Content guide to the new consolidated, replatformed guides setup.

As with the migration of all guides, we will also be using this opportunity to refine the guide/checklist for migrating individual guides.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

Most of the steps we expect to follow can be found in the draft individual migration guide document. From a high level, these include:

Soft release

• Make sure that all pre-migration issues have been completed and that the specific guide is prepared (tests are passing, there are no TODO links left over
• Confirm DNS records are up-to-date for the OLD guide domain
• Remove redirects from the new URL to the old guides (ie, stop guides.18f.gov/[guide-name] from redirecting to [guide-name].18f.gov)
• Add the new guide in the Search.gov admin panel instructions

Hard release

• Permanently redirect old guide URLs to the new guide (ie, [guide-name].18f.gov/etc/etc2/ redirects to guides.18f.gov/[guide-name]/etc/etc2/)

Post release

• Monitor analytics for the new site for some specified period of time
• Update 18f.gsa.gov website to use new guides link
• Turn on automatic reviewer tagging for guide
• Update the working migration doc with any refinements of the process, to make future migrations easier

Other resources

• pages-redirects repository where the routing changes will be made (see the migration doc)

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
The changes should be straightforward, but the merge and deploy of reroutes will take an unspecified amount of time, as it relies upon Cloud-gov's internal processes.

Acceptance Criteria

• guides.18f.gov/content-guide/ points to the new, live, replatformed Content guide
• Analytics is able to show incoming data for the new Content guide after some specified period of time
• We have a refined migration doc available for future migrations

Add context to "New teammate info" document

A description of the work

We have a "New teammate info" doc for any folks joining TLC and doing Guides work for the first time.

Right now, the information is mostly general and context-based. It would be helpful to add some technical/engineering background information.

@echappen flagged a number of items that could be described, including:

• Who to tag in PR’s?
• What is definition of Done for a PR?
• Git commit strategy? (Example: are squashes okay?)
• Any strategies for reviewing code? (Example: should you be explicit when something is a blocker?)
• Dependency management?

It would also be helpful to describe the process for getting added to the search panel.

@eric-gade and @igorkorenfeld , you may be best suited to answer some of these questions/fill out this context.

Point of contact on this issue

Who can we follow-up with if we have questions?
@christophermather

Reproduction steps (if necessary)

Be as specific as possible

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

Acceptance Criteria

• Our "New teammate info" document has more engineering context
• Engineering folks starting on Guides work have important info that they need in order to being work

Tasks

• [ ]

Migrate the De-risking guide to the new setup

🟢 DE-RISKING IS READY TO GO 🟢

A description of the work

We will migrate the De-risking guide to the new consolidated, replatformed guides setup.

As with the migration of all guides, we will also be using this opportunity to refine the guide/checklist for migrating individual guides.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

Most of the steps we expect to follow can be found in the draft individual migration guide document. From a high level, these include:

Soft release

• Make sure that all pre-migration issues have been completed and that the specific guide is prepared (tests are passing, there are no TODO links left over
• Confirm DNS records are up-to-date for the OLD guide domain
• Remove redirects from the new URL to the old guides (ie, stop guides.18f.gov/[guide-name] from redirecting to [guide-name].18f.gov)
• Add the new guide in the Search.gov admin panel instructions

Hard release

• Permanently redirect old guide URLs to the new guide (ie, [guide-name].18f.gov/etc/etc2/ redirects to guides.18f.gov/[guide-name]/etc/etc2/)

Post release

• Monitor analytics for the new site for some specified period of time
• Update 18f.gsa.gov website to use new guides link
• Turn on automatic reviewer tagging for guide
• Update the working migration doc with any refinements of the process, to make future migrations easier

Other resources

• pages-redirects repository where the routing changes will be made (see the migration doc)

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
The changes should be straightforward, but the merge and deploy of reroutes will take an unspecified amount of time, as it relies upon Cloud-gov's internal processes.

Acceptance Criteria

• guides.18f.gov/derisking/ points to the new, live, replatformed De-risking guide
• Analytics is able to show incoming data for the new De-risking guide after some specified period of time
• We have a refined migration doc available for future migrations

Migrate the Product guide to the new setup

🟢 PRODUCT IS READY TO GO 🟢

A description of the work

We will migrate the Product guide to the new consolidated, replatformed guides setup.

As with the migration of all guides, we will also be using this opportunity to refine the guide/checklist for migrating individual guides.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

Most of the steps we expect to follow can be found in the draft individual migration guide document. From a high level, these include:
Soft release

• Make sure that all pre-migration issues have been completed and that the specific guide is prepared (tests are passing, there are no TODO links left over
• Confirm DNS records are up-to-date for the OLD guide domain
• Remove redirects from the new URL to the old guides (ie, stop guides.18f.gov/[guide-name] from redirecting to [guide-name].18f.gov)
• Add the new guide in the Search.gov admin panel instructions

Hard release

• Permanently redirect old guide URLs to the new guide (ie, [guide-name].18f.gov/etc/etc2/ redirects to guides.18f.gov/[guide-name]/etc/etc2/)

Post release

• Monitor analytics for the new site for some specified period of time
• Update 18f.gsa.gov website to use new guides link
• Turn on automatic reviewer tagging for guide
• Update the working migration doc with any refinements of the process, to make future migrations easier

Other resources

• pages-redirects repository where the routing changes will be made (see the migration doc)

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
The changes should be straightforward, but the merge and deploy of reroutes will take an unspecified amount of time, as it relies upon Cloud-gov's internal processes.

Acceptance Criteria

• guides.18f.gov/product/ points to the new, live, replatformed Product guide
• Analytics is able to show incoming data for the new Product guide after some specified period of time
• We have a refined migration doc available for future migrations

[EPIC] Incremental UX improvements to existing Guides

A description of the work

We have a set of recommendations for incremental improvements to the UX of the existing Guides. These recommendations should be implemented as we replatform or after we replatform. These improvements do not need to be implemented on the current Guides sites.

These recommendations fall into several categories:

Now
#143
#144
#145

Next
Issues generated from other recommendations from Aviva's document

Later
Another round of UX research/recommendations
Issues generated from these new rec's

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

No response

Tasks

Beta Give feedback

1. Remove landing page from Engineering Guide #143
   Guides Initiative 2 +2
2. Ensure top-level page displays in sidebar nav on UX guide #144
   Guides Initiative 2 +2
3. Discuss how to prioritize UX improvements #145
   Guides Initiative 2 +2

[HOLD] Permanently delete old Guides Cloud Pages sites

🚨DO NOT DO THIS TASK UNTIL ALL OTHER MIGRATION TASKS ARE COMPLETE🚨

Background

This is the final step from our Guide to migrating a guide, and the final step of our migrating our guides to their new home.

Please make sure that all of the guides have completed all of the steps from the Guide to migrating a guide (and their respective "Migrate" issues).

Pre-req

• https://github.com/18F/TLC-crew/issues/447
• #159
• #160
• #161
• #162
• #163
• #164
• #165
• #166

The work

Once we are confident that traffic is being redirected appropriately, you can go ahead and delete the Cloud.gov Pages site for each old individual guides site. This is necessary in order to prevent extra charges.

In the Cloud.gov Pages control panel, navigate to the name of the old guide repository. For example, for agile we would go to this link and follow the link to the site administration page:


Click “site settings” and navigate to the “advanced settings,” where you will see an option to delete the site:

If you do not have the appropriate privileges to delete, contact the site’s github repository maintainer/administrator.

Repeat this task for each of the guides:

• Agile
• Content
• Engineering
• Product
• User Experience
• Brand
• De-risking
• Engineering Hiring
• Accessibility

Target date of completion

December 31, 2023

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

• All old guides Cloud Pages sites are deleted
• We are no longer being charged for these sites

Create issues for remainder of replatforming work

A description of the work

We need to scope out the remainder of the Guides replatforming work and create issues for that work. The work will fall into a few buckets:

Prep work

• Resolve outstanding TODOS in the code for each guide
• Thorough visual comparison of each guide against existing guides

Migration work

• Update the client side redirect and site indexing
• Add the new guide in the Search.gov admin panel
• Permanently redirect old guide URL to the new guide URL
• Monitor Analytics
• Update the link on the guides homepage
• Permanently delete old guides Cloud Pages site

Our theory is that some of this work can be batched and that some of those batches can be executed in parallel.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

2 days

Acceptance Criteria

To the best of our ability, the work remaining for the Guides migration is scoped out in issues and sequenced in the Guides/TLC backlog.

Explore options for re-enabling search on the re-platformed Guides and Methods

We need an ADR that explores available options to re-enabling search on the replatformed Guides and Methods. This will be shared with @christophermather and @adunkman and we'll make a call on the way forward that takes into account the future state of the G+M.

List possible options and tradeoffs.

eslint setup, configuration, and CI

We should add some basic eslint settings for this project, as well as a way to run the checker locally and as a Github Action.

Re-enable search functionality site wide

Description

Both #91 and #92 led to us having to temporarily disable/hide the search feature site-wide. Once those are resolved, we should re-enable the search feature and display the search bar on guide pages where it was previously available

test

test test

Implement new 404 page design

From #84 , let's implement @melchoyce's new 404 design. A few notes:

• The page should inherit site defaults for header, nav, footer, etc.
• Per #97 , the header will actually be "Guides" rather than "Approaches
• We're implementing the left-aligned design (see below)
• "Contact us" should link to https://18f.gsa.gov/contact/
• "Visit homepage" should go to the overall Guides homepage (18f.gsa.gov/guides/)

Acceptance criteria:

• Any user trying to access a URL that can't be found on the Guides site encounters this redesigned 404 page

test

test

Summarize Search.gov integration needs and break out into individual tickets

A description of the work

Based on our conversation with Search.gov, let's clearly articulate what our next steps are for implementation of search on the replatformed guides.

Some questions:

• When does search get activated?
• What implementation quirks do we need to stay mindful of?
• What kind of coordination do we need to maintain with the Search.gov team?

Point of contact on this issue

Who can we follow-up with if we have questions?

Reproduction steps (if necessary)

Be as specific as possible

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

Acceptance Criteria

• We have a shared understanding of how we'll roll out Search when replatforming guides
• We have an epic issue for Search that lists out tasks and any dependencies between them
• We have clear issues tasked out in the backlog

Tasks

• [ ]

Discuss how to prioritize UX improvements

A description of the work

We have a suite of UX recommendations from a round of UX research conducted by @AvivaOskow and @AnitaYCheng. We've already implemented some rec's and a few more are ready to be prioritized in our backlog. Soon, we may have more UX improvements.

I'd like to discuss the best strategy for implementing these improvements.

Option 1: Hold until all guides are replatformed.

• Pro: Least risky
• Con: defers improvements, ambiguous timeline

Option 2: Implement as we go

• Pro: improvements roll out as replatformed guides do
• Con: could gum up our process and make it harder to roll out and/or predict rollout timeline

Option 3: ??

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

• We know how we're prioritizing UX improvements going forward
• If need be, we have a decision-making rubric for prioritization

Migrate the Engineering guide to the new setup

🟢 ENGINEERING IS READY TO GO 🟢

A description of the work

We will migrate the Engineering guide to the new consolidated, replatformed guides setup.

As with the migration of all guides, we will also be using this opportunity to refine the guide/checklist for migrating individual guides.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

Most of the steps we expect to follow can be found in the draft individual migration guide document. From a high level, these include:

Soft release

• Make sure that all pre-migration issues have been completed and that the specific guide is prepared (tests are passing, there are no TODO links left over
• Confirm DNS records are up-to-date for the OLD guide domain
• Remove redirects from the new URL to the old guides (ie, stop guides.18f.gov/[guide-name] from redirecting to [guide-name].18f.gov)
• Add the new guide in the Search.gov admin panel instructions

Hard release

• Permanently redirect old guide URLs to the new guide (ie, [guide-name].18f.gov/etc/etc2/ redirects to guides.18f.gov/[guide-name]/etc/etc2/)

Post release

• Monitor analytics for the new site for some specified period of time
• Update 18f.gsa.gov website to use new guides link
• Turn on automatic reviewer tagging for guide
• Update the working migration doc with any refinements of the process, to make future migrations easier

Other resources

• pages-redirects repository where the routing changes will be made (see the migration doc)

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
The changes should be straightforward, but the merge and deploy of reroutes will take an unspecified amount of time, as it relies upon Cloud-gov's internal processes.

Acceptance Criteria

• guides.18f.gov/engineering/ points to the new, live, replatformed Engineering guide
• Analytics is able to show incoming data for the new Engineering guide after some specified period of time
• We have a refined migration doc available for future migrations

Remove landing page from Engineering Guide

A description of the work

Background: The Engineering Guide lands on a table of contents page. This is inconsistent with other guides and is inaccessible from other parts of the guide. It should be removed.

To-do: remove the landing page from the Engineering Guide (see below for visual). When users navigate to https://engineering.18f.gov/, they should instead land on About this guide.

If you're new to Guides work, read this! New teammate info

Point of contact on this issue

Who can we follow-up with if we have questions?

Reproduction steps (if necessary)

Be as specific as possible

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

Acceptance Criteria

• Engineering guide landing page has been removed
• https://engineering.18f.gov/ now resolves to "About this guide"

ex: As an 18F staff member who is going on parental leave, I can navigate to my
latest Tock reporting period and choose billing line #1810 by filtering by
number or "extended OOO"

Create a launch list for rolling out replatformed guides

A description of the work

This may already exist, but surfacing here in case we need to create and/or add to a launch list.

There's some complexity in rolling out each replatformed guide and a few steps that need to unfold in sequence for us to deliver expected functionality and maintain compliance. Some items that come to mind:

• When does search get activated? What implementation quirks do we need to stay mindful of? What kind of coordination do we need to maintain with the Search.gov team?
• When do redirects get implemented?
• When does the link on https://18f.gsa.gov/guides/ get updated?
• What else?

Point of contact on this issue

Who can we follow-up with if we have questions?
@christophermather

Reproduction steps (if necessary)

Be as specific as possible

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

Acceptance Criteria

• We have a launch list that has been reviewed and agreed upon by engineers + Guides PM
• We update the launch list with learnings after each guides rollout

Tasks

• [ ]

Fix missing parentheses in .pa11yci config

A description of the work

I see missing closing ' and closing ] in our .pa11yci config file:

a[href*='/TODO/"

(https://github.com/18F/guides/blob/main/.pa11yci#L6)

Point of contact on this issue

Alex Soble, Eleni Chappen

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

Hours

Acceptance Criteria

A very minimal approach to fixing this would be to close the missing quotation mark and bracket.

All of our pa11y checks are green (passing), despite the missing characters here.

A more robust approach to this would be to make sure that this pa11y config is working as intended.

Search does not work

Description

The search feature does not work across the site, and leads to the 404 page.

Part of the task should be to communicate with search.gov and figure out how we can have separate search results on a per-guide basis, given that this is all running on one site.

Bug: fix styling for 404 page

The 404 page could use some design love, like a grid-container around the main content.

This may also entail finding a solution for fixing the footer to the bottom of the viewport when page content is really short.

Screenshot of current state:

Develop estimate for Methods replatforming work

A description of the work

As discussed, we are evaluating the replatforming of Methods pages separately from the other Guides due to their dissimilarity.

Right now, we lack an understanding of how complex the replatforming effort for these pages will be.

We need to do a little digging to develop an estimate for how much effort it will take to replatform. This estimate can be rough: we want medium-high confidence but only need low fidelity. Meaning:

• This is way easier than we thought. Compared to the Agile guide, it will take less effort..
• This is about as complex as we thought. It's at least as much more work as the Agile guide.
• This is far more complex than we expected. It's hard to estimate how much work it will take to complete.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

• We have a rough understanding (and estimate) of level of effort to replatform the Methods pages

Migrate the Accessibility guide to the new setup

🟢 ACCESSIBILITY IS READY TO GO 🟢

A description of the work

We will migrate the accessibility guide to the new consolidated, replatformed guides setup.

As with the migration of all guides, we will also be using this opportunity to refine the guide/checklist for migrating individual guides.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

Most of the steps we expect to follow can be found in the draft individual migration guide document. From a high level, these include:

Soft release

• Make sure that all pre-migration issues have been completed and that the specific guide is prepared (tests are passing, there are no TODO links left over
• Confirm DNS records are up-to-date for the OLD guide domain
• Remove redirects from the new URL to the old guides (ie, stop guides.18f.gov/[guide-name] from redirecting to [guide-name].18f.gov)
• Add the new guide in the Search.gov admin panel instructions

Hard release

• Permanently redirect old guide URLs to the new guide (ie, [guide-name].18f.gov/etc/etc2/ redirects to guides.18f.gov/[guide-name]/etc/etc2/)

Post release

• Monitor analytics for the new site for some specified period of time
• Update 18f.gsa.gov website to use new guides link
• Turn on automatic reviewer tagging for guide
• Update the working migration doc with any refinements of the process, to make future migrations easier

Other resources

• pages-redirects repository where the routing changes will be made (see the migration doc)

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
The changes should be straightforward, but the merge and deploy of reroutes will take an unspecified amount of time, as it relies upon Cloud-gov's internal processes.

Acceptance Criteria

• guides.18f.gov/accessibility/ points to the new, live, replatformed Accessibility guide
• Analytics is able to show incoming data for the new Accessibility guide after some specified period of time
• We have a refined migration doc available for future migrations

Review and address open TODOs in the guides

A description of the work

This is part of step 1 in the 18F guide to migrating a guide.

As a part of preparing the remaining guides for migration, we need to go through and address all outstanding TODOs in the code. You can find these open TODOs by clicking this link.

You can also see all of these TODOs in this spreadsheet for ease of sorting.

Some stats:

• About a dozen TODOs are for replacement links to GitHub URLs (links to contributing files, new issue links, other repository links). These are changing because we've consolidated our repos into a new one. We'll need to identify the appropriate new URLs and swap them in for these TODOs.
• A whopping 36 of 57 TODOs are links to Methods. We can simply restore the original URLs here. We originally thought that we'd have new URLs before launch, but that won't be the case.
• Also, a whopping 44 of 57 TODOs are in the UX Guide (again, most of those are Methods links)
• Another 7 TODOs need a little research - they're either unclear (to me, a non-engineer) or broken external links.

Here's a little breakdown of TODOs by guide and recommend resolution:

Guide	Don't fix	Needs research	Replace URL	Restore URL	Grand Total
Accessibility		1	1		2
Brand			1		1
Content Guide			3		3
Engineering	1		2		3
Engineering Hiring			1		1
N/A		1			1
Product			1	1	2
UX Guide	1	5	3	35	44
Grand Total	2	7	12	36	57

Recommended steps
If it's possible to do a batch fix across all guides for Methods links, do that. That eliminates 36 TODOs right off the bat.

If not/then we should address the TODOs guide-by-guide. Here's the recommended order:

Should be easy:

1. Brand @melchoyce
2. Engineering Hiring @alexsobledotgov
3. Product @jskinne3
4. Engineering @alexsobledotgov
5. Content Guide @melchoyce

Needs a little attention
6. Accessibility @melchoyce

Might take some time
7. UX Guide @jskinne3 @melchoyce @alexsobledotgov (team effort!)

Note: the De-risking guide had no TODOs associated with it, so it is ready for #167

Order of operations

1. Pick which guide you're going to address and assign yourself above and in this spreadsheet
2. If it's unclear what link should be used, make a best guess and confirm w/ @echappen or @christophermather
3. Make changes in the markdown file
4. Make pull request and put issue "in review" in spreadsheet
5. @echappen reviews PR and approves
6. Mark it "done" in spreadsheet

Once all TODOs are done for a particular guide, let @christophermather and/or check it off in the below Tasks list.

Point of contact on this issue

@christophermather

Acceptance criteria

• A search of our code yields no outstanding TODOs

Tasks

Beta Give feedback

1. Brand guide TODOs are done
2. Engineering Hiring guide TODOs are done
3. Product guide TODOs are done
4. Engineering guide TODOs are done
5. Content guide TODOs are done
6. Accessibility guide TODOs are done
7. UX guide TODOs are done

Migrate the Brand guide to the new setup

🟢 BRAND IS READY TO GO 🟢

A description of the work

We will migrate the Brand guide to the new consolidated, replatformed guides setup.

As with the migration of all guides, we will also be using this opportunity to refine the guide/checklist for migrating individual guides.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

Most of the steps we expect to follow can be found in the draft individual migration guide document. From a high level, these include:

Soft release

• Make sure that all pre-migration issues have been completed and that the specific guide is prepared (tests are passing, there are no TODO links left over
• Confirm DNS records are up-to-date for the OLD guide domain
• Remove redirects from the new URL to the old guides (ie, stop guides.18f.gov/[guide-name] from redirecting to [guide-name].18f.gov)
• Add the new guide in the Search.gov admin panel instructions

Hard release

• Permanently redirect old guide URLs to the new guide (ie, [guide-name].18f.gov/etc/etc2/ redirects to guides.18f.gov/[guide-name]/etc/etc2/)

Post release

• Monitor analytics for the new site for some specified period of time
• Update 18f.gsa.gov website to use new guides link
• Turn on automatic reviewer tagging for guide
• Update the working migration doc with any refinements of the process, to make future migrations easier

Other resources

• pages-redirects repository where the routing changes will be made (see the migration doc)

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
The changes should be straightforward, but the merge and deploy of reroutes will take an unspecified amount of time, as it relies upon Cloud-gov's internal processes.

Acceptance Criteria

• guides.18f.gov/brand/ points to the new, live, replatformed Brand guide
• Analytics is able to show incoming data for the new Brand guide after some specified period of time
• We have a refined migration doc available for future migrations

Gather context: content strategy for 18F guides

A description of the work

This will likely turn into an epic.

Need to partner with a content person to plot the path forward for establishing our content strategy for 18F guides. The priority outcome right now is a clear definition of what kind of content is uniquely suited for the 18F guides website.

This definition balances compliance, policy, brand, and audience needs (among other things).

Point of contact on this issue

No response

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

• Decision-making rubric for what content is uniquely suited to 18F Guides

Ensure top-level page displays in sidebar nav on UX guide

A description of the work

This is an issue that affects three sections of the UX guide:

• Our Approach
• Research
• Design

When you navigate to each of these three sections, the top-level page does not appear in the sidebar nav.

For instance, navigating to Our Approach, the first item in the sidebar nav is "Values and principles". In order to follow design conventions in other guides, the first item in the sidebar nav should be "Our Approach".

Likewise, the first item in the sidebar nav under Research should be "Research" and the first sidebar item under Design should be "Design".

If you're new to Guides work, read this! New teammate info

Point of contact on this issue

Who can we follow-up with if we have questions?

Reproduction steps (if necessary)

Be as specific as possible

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

Acceptance Criteria

• This sidebar fix is applied to all three sections mentioned: Our Approach, Research and Design

ex: As an 18F staff member who is going on parental leave, I can navigate to my
latest Tock reporting period and choose billing line #1810 by filtering by
number or "extended OOO"

Temporarily hide search bar and functionality

Description

As a way to partially deal with #91 while we continue to migrate guides, we should temporarily disable the search functionality by not showing the search bar. This change should be made site-wide.

Review redesign checklist w/ TTS Outreach

When we’re preparing for the relaunch of the redesigned guides, we need to complete the Go-Live Checklist for Federal Websites and Digital Services (make a copy) and review with @katelandisgsa — as she and I discussed last week, we’ll want to touch base at the ~80% complete mark so we can make adjustments as needed.

Since we’re separating the technical consolidation from redesign, we’ll want to follow the checklist at the redesign phase, rather than the technical consolidation phase. We should follow the "Redesign" tab, not the "Site Launch" tab.

Manage Dependabot minor and major updates (increment)

Per this decision, now that patches are auto-merged, we will still need human maintenance for minor and major Dependabot updates.

temporarily remove auto-merging of Dependabot patches

Per this decision, we will auto-merge Dependabot patches.

Per the discussion below, we will remove auto-merging temporarily while we figure out the errors around it in #211

Restore search bar to site

We need to uncomment the code here that removed the search bar from displaying to the user. This should only happen once search has been properly enabled for at least the first guide (agile) in this ticket.

Fix a11y issue on heading permalink icons

A description of the work

In reviewing the work on #341 @jasnakai noted that the way the permalink icons are implemented on headings in the replatformed guides (i.e. the link icon next to headings) is not properly structured. Namely, the <a> element is in a span element that have an aria-hidden=true attribute, but the anchor is focusable. We should edit the current implementation so that it is properly structured for accessibility. Note that the implementation on the guides is borrowed from the TTS handbook, so any finding here should be applied to the handbook as well (though not necessarily as part of work on this issue).

Our current implementation uses the markdown-it-anchor plugin, which has been updated with more accessible options. It would be good to see if any of the recent updates may be useful to us.

Point of contact on this issue

Who can we follow-up with if we have questions?
@jasnakai

Reproduction steps (if necessary)

Be as specific as possible

Billable?

• Yes
• No

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

Medium size

Acceptance Criteria

• The permalink icons are structured in an accessible way.

Implement "More 18F Guides" button

A description of the work

Building off of https://github.com/18F/TLC-crew/issues/507

We'd like to implement a "More 18F Guides" button on individual guides. The link will say "More 18F Guides", sit in the secondary navigation and link to https://18f.gsa.gov/guides/

The intent is for this link to be implemented on the replatformed guides.

Methods:

Other guides:

Mobile:

Point of contact on this issue

Who can we follow-up with if we have questions?

Reproduction steps (if necessary)

Be as specific as possible

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

Acceptance Criteria

• The replatformed guides template has a "More 18F Guides" button in the secondary navigation

Create "Buy Better" section in IA staging sandbox

A description of the work

Take the information architecture laid out in this spreadsheet and recreate it in the staging environment that we stood up in #128.

For now, let's focus only on the "Buy Better" section.

@dluetger has mocked up two options:

Option 1:

Option 2:

Point of contact on this issue

Who can we follow-up with if we have questions?

Reproduction steps (if necessary)

Be as specific as possible

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

<1 increment

Acceptance Criteria

• We have a working prototype of a "Buy Better" guide in a staging environment

Migrate the Engineering Hiring guide to the new setup

🟢 ENGINEERING HIRING IS READY TO GO 🟢

A description of the work

We will migrate the Engineering Hiring guide to the new consolidated, replatformed guides setup.

As with the migration of all guides, we will also be using this opportunity to refine the guide/checklist for migrating individual guides.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

Most of the steps we expect to follow can be found in the draft individual migration guide document. Most of the steps we expect to follow can be found in the draft individual migration guide document. From a high level, these include:
Soft release

• Make sure that all pre-migration issues have been completed and that the specific guide is prepared (tests are passing, there are no TODO links left over
• Confirm DNS records are up-to-date for the OLD guide domain
• Remove redirects from the new URL to the old guides (ie, stop guides.18f.gov/[guide-name] from redirecting to [guide-name].18f.gov)
• Add the new guide in the Search.gov admin panel instructions

Hard release

• Permanently redirect old guide URLs to the new guide (ie, [guide-name].18f.gov/etc/etc2/ redirects to guides.18f.gov/[guide-name]/etc/etc2/)

Post release

• Monitor analytics for the new site for some specified period of time
• Update 18f.gsa.gov website to use new guides link
• Turn on automatic reviewer tagging for guide
• Update the working migration doc with any refinements of the process, to make future migrations easier

Other resources

• pages-redirects repository where the routing changes will be made (see the migration doc)

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
The changes should be straightforward, but the merge and deploy of reroutes will take an unspecified amount of time, as it relies upon Cloud-gov's internal processes.

Acceptance Criteria

• guides.18f.gov/eng-hiring/ points to the new, live, replatformed Engineering Hiring guide
• Analytics is able to show incoming data for the new Engineering Hiring guide after some specified period of time
• We have a refined migration doc available for future migrations

Update DNS records for all remaining OLD guides domains

A description of the work

This mitigates server-side disruption when deploying a permanent redirect for a guide (the next step).
DNS records need to be compatible with Cloud’s new external-domain service, and many of 18F’s domains are not up-to-date with this service. Higher-level background and instructions can be found here.

Create a Pull Request with updates similar to this example on the 18F/dns repository for each old guide domain. Tag anyone from the cloud team (or anyone on the TLC Crew with write access to that repo) as a reviewer.

On early Tuesday, Wednesday, and Thursday mornings, the cloud.gov migrator will update the background domain service. Once the DNS records are updated and run through the migration process, proceed to the next step.

[Update: there is a draft pull request for updating all remaining guides domains. This should be merged and migrated (as described above) prior to moving on to the next step]

Note: This task blocks any work related to migration step 5 / permanent redirects

Point of contact on this issue

@echappen

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

• Confirm that cloud.gov migrator has successfully updated the DNS records

Adjust migration strategy based on Cloud.gov feedback

A description of the work

Based on this Slack conversation with Cloud.gov, we need to determine what - if any - new steps we need to add to our launch list/migration strategy for each guide that we roll out.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

• Discuss recommendations
• Decide if we need to adjust strategy or add steps
• Add those steps to both GitHub issues and our Guide to migrating a guide

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

• Cloud.gov conversation has been reviewed and discussed
• New steps for guide launch strategy - if any - have been established
• Those new steps have been added to our Guide to migrating a guide
• Those steps have been added to GitHub guide migration issues

[EPIC]: Finish migrating the guides

A description of the work

We have 9 guides that we need to replatform. This issue is an overarching EPIC ticket to track the whole of this work.

Context: a lot of work has already gone into the replatforming effort. This epic gathers the final steps to completing the migration.

Release Milestones

1. Content/design is fully prepared for release
2. Client-side redirects are removed; site is indexable ("soft" launch)
3. Guide is visible in search.gov results
4. Old url permanently redirects to new url ("hard" launch)
5. Guides homepage uses new url
6. Analytics monitoring period is complete
7. Old guides Cloud Pages site is deleted
8. Old guide Github repo is archived

Guide	1	2	3	4	5	6	7	8
Accessibility	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢
Agile	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢
Brand	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢
Content	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢
De-risking	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢
Engineering	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢
Engineering Hiring	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢
Product	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢
User Experience	🟢	🟢	🟢	🟢	🟢	🟢	🟢	🟢

Release Milestones are based on the steps in the Migration Guide

Point of contact on this issue

@christophermather

Agile: https://github.com/18F/TLC-crew/issues/447

Pre-Migration

Beta Give feedback

1. Adjust migration strategy based on Cloud.gov feedback #168
   Guides Initiative 2 +2
   
2. Review and address open TODOs in the guides #157
   7 of 7
   Guides Initiative 2 +2
   

   
3. Visually compare migrated guides against existing guides #167
   8 of 8
   Guides Initiative 2 +2
   
4. Update DNS records for all remaining OLD guides domains #177
   Guides Initiative 2 +2
5. Accessibility Guide: "Other .Gov Accessibility sites" link yields a 404 #203
   Guides Initiative 2 +2
   
6. Fix a11y issue on heading permalink icons #104
   Guides Initiative 2 +2
   
7. Create step-by-step for accessing + monitoring Guides analytics #204
   Guides Initiative 2 +2
   
8. Confirm that all icon-related work is complete #205
   Guides Initiative 2 +2
   
9. Create communications for G&M schedule #219
   Guides Initiative 2 +2
   

Migration

Beta Give feedback

1. Migrate the Brand guide to the new setup #164
   Guides Initiative 2 +2
   
2. Migrate the Content guide to the new setup #160
   Guides Initiative 2 +2
   
3. Migrate the User Experience guide to the new setup #163
   Guides Initiative 2 +2
   
4. Migrate the De-risking guide to the new setup #166
   Guides Initiative 2 +2
   
5. Migrate the Accessibility guide to the new setup #159
   Guides Initiative 2 +2
   
6. Migrate the Engineering guide to the new setup #161
   Guides Initiative 2 +2
   
7. Migrate the Product guide to the new setup #162
   Guides Initiative 2 +2
   
8. Migrate the Engineering Hiring guide to the new setup #165
   Guides Initiative 2 +2
   
9. [HOLD] Permanently delete old Guides Cloud Pages sites #175
   Guides Initiative 2 +2
10. Archive old guide repositories (post-migration) #342
    Guides Initiative 2 +2

Create a branch of the Guides repo for information architecture prototyping

A description of the work

We'd like to prototype some new information architecture. In order to do that, we need to make a branch of the guides repo for us to play around in, independent of the ongoing replatforming work.

Blocks #129

Point of contact on this issue

Who can we follow-up with if we have questions?
@christophermather

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?

<1 increment

Acceptance Criteria

1. We have a branch that we can use as a sandbox for testing out a new information architecture

• URL: https://github.com/18F/guides/tree/kbighorse-information-architecture-prototyping

3. Sandbox is available to stakeholders (only) over the Internet

• URL: https://federalist-8bc0b42c-5fd0-4ae8-9366-cd9c265a4446.sites.pages.cloud.gov/preview/18f/guides/kbighorse-information-architecture-prototyping/

4. Owner of #129 is able to modify the content to create new section
5. Design is able to access published site for testing purposes
   (last 2 ACs are out-of-scope here: cloud.gov Pages handles access)

Visually compare migrated guides against existing guides

A description of the work

This is part of step 1 in the 18F guide to migrating a guide. This task follows #157.

As a final step before starting migration steps, we need to visually compare migrated guides against existing guides to do a final validation pass that they are ready to migrate.

Ready for review

Based on completed tasks from #157

• De-risking (@a-chappelear )
• Engineering Hiring (@a-chappelear )
• Accessibility (@qmanderson1)
• Content (@a-chappelear)
• Brand (@a-chappelear)
• Engineering (@a-chappelear)
• Product (@a-chappelear)
• User Experience (@a-chappelear)

Point of contact on this issue

@christophermather

Our evaluation rubric

Parity not perfection!

We want to make sure that we're not losing any functionality. If we come across any errors or problems that exist on both sites, we should log them in our tracker spreadsheet. We will add them to the backlog and address post-migration.

Reproduction steps

This will involve a manual click-through of sites. Meaning:

1. Pull up the replatformed guide URL in one window
2. Pull up the corresponding existing guide URL in another
3. Scan each page for visual similarity/uniformity
4. Make note of any (significant) discrepancies. You can add these discrepancies to this tracker spreadsheet.
5. If no discrepancies, mark that guide as complete in task list below
6. If discrepancies, review w/ @christophermather and add issues to the backlog

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Engineering Hiring
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

• All replatformed guides have been checked against the existing guides
• Guides that are ready are given the greenlight
• Guides that have any discrepancies have been flagged as blocked and discrepancies have been turned into issues in the backlog

Tasks

Beta Give feedback

1. Accessibility guide visual comparison complete
2. Content guide visual comparison complete
3. De-risking guide visual comparison complete
4. Engineering guide visual comparison complete
5. Product guide visual comparison complete
6. User Experience guide visual comparison complete
7. Brand guide visual comparison complete
8. Engineering Hiring guide visual comparison complete

Add code style configuration to development workflow

As we get more contributors to the guides repo, we'll get more discrepancies in code styling.

Adding something like Prettier to the dev pipeline will solve discrepancies in individual contributor styling preferences.

Migrate the User Experience guide to the new setup

🟢 UX IS READY TO GO 🟢

A description of the work

We will migrate the UX guide to the new consolidated, replatformed guides setup.

As with the migration of all guides, we will also be using this opportunity to refine the guide/checklist for migrating individual guides.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

Most of the steps we expect to follow can be found in the draft individual migration guide document. From a high level, these include:
Soft release

• Make sure that all pre-migration issues have been completed and that the specific guide is prepared (tests are passing, there are no TODO links left over
• Confirm DNS records are up-to-date for the OLD guide domain
• Remove redirects from the new URL to the old guides (ie, stop guides.18f.gov/[guide-name] from redirecting to [guide-name].18f.gov)
• Add the new guide in the Search.gov admin panel instructions

Hard release

• Permanently redirect old guide URLs to the new guide (ie, [guide-name].18f.gov/etc/etc2/ redirects to guides.18f.gov/[guide-name]/etc/etc2/)

Post release

• Monitor analytics for the new site for some specified period of time
• Update 18f.gsa.gov website to use new guides link
• Turn on automatic reviewer tagging for guide
• Update the working migration doc with any refinements of the process, to make future migrations easier

Other resources

• pages-redirects repository where the routing changes will be made (see the migration doc)

Billable?

• Yes
• No
  If yes, tock code:

Skills needed

• Any human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
The changes should be straightforward, but the merge and deploy of reroutes will take an unspecified amount of time, as it relies upon Cloud-gov's internal processes.

Acceptance Criteria

• guides.18f.gov/ux-guide/ points to the new, live, replatformed UX guide
• Analytics is able to show incoming data for the new UX guide after some specified period of time
• We have a refined migration doc available for future migrations

[EPIC] Search implementation epic

A description of the work

We're replatforming our guides. As part of that effort, we need to enable search in a different way. There are several issues describing that work.

Point of contact on this issue

Who can we follow-up with if we have questions?
@christophermather

Tasks

• https://github.com/18F/TLC-crew/issues/514

Tasks

Beta Give feedback

1. Search does not work #91
   bug +1
2. Explore options for re-enabling search on the re-platformed Guides and Methods #96
   Guides Initiative 2 +2
   

   
3. https://github.com/18F/TLC-crew/issues/514
4. https://github.com/18F/TLC-crew/issues/526
5. Restore search bar to site #114
   +0
   
6. https://github.com/18F/TLC-crew/issues/530
7. Re-enable search functionality site wide #93
   +0
8. Summarize Search.gov integration needs and break out into individual tickets #106
   Initiative 2 +1
   

Explore ways to make pa11y CI runs faster

The pa11y CI check for the guides repo is starting to have the same issue as 18f.gsa.gov: pa11y CI checks are becoming too slow for daily development. For guides, a pa11y check on Github Actions can take anywhere from 5 to 15 minutes.

This check will get slower as the guides repo grows. It would be good to explore ways to make this CI check faster.

Possible user story: As a maintainer of the guides, I'd like to have faster feedback from CI builds, so that I can complete more tasks in a day.

Context gathering: Meet with Digital.gov to understand their mission and process

A description of the work

Continuing to gather some context, this time with external folks.

It would be useful to meet with Digital.gov to better understand their mission and process. This information will be useful in two ways:

• It may aid in our understanding of our own mission and process
• It could flag potential areas of convergence that our teams want to explore together

As of right now, these conversations would be purely informational.

Point of contact on this issue

@christophermather

Reproduction steps (if necessary)

No response

Skills Needed

• Any Human
• Design
• Content
• Engineering
• Acquisition
• Product
• Other

Does this need to happen in the next 2 weeks?

• Yes
• No

How much time do you anticipate this work taking?

No response

Acceptance Criteria

• We have a better understanding of how Digital.gov evaluates and accepts content for their site