Updating the Handbook

Everyone – inside and outside TTS – can submit contributions to the Handbook. If there's something missing, a piece of information is outdated, or something is broken, you're allowed and encouraged to submit a fix! This guide is meant to help you get started and provide documentation for the Handbook's various components and utilities that make editing easier.

Disclaimers and cautions

Before you make your contribution, there are a few things to remember:

• This Handbook website and repository are public. Use links to internal Google Docs, Sheets, etc. for anything that shouldn't be publicly visible.
• We're careful about publishing information collected during research; , external,TTS-only, learn more and ask , external,TTS-only, the research guild for guidance first.
• Avoid "click here" links. Follow the , external,A11Y Project Anchor Link Patterns.
• We follow the structure outlined in the , external,18F Content Guide.

There is also some information that should not be included in the Handbook:

• We receive training on this, but here are a few reminders about things we shouldn't include in the Handbook:

  • Sensitive information

  • Comments that can be easily interpreted as , external,endorsements (or other potential ethical issues)

  • Information that can easily go out of date and is already published somewhere else in a useful format. This includes:

    • People's email addresses and phone numbers, even if it is public information. We typically link to group/team email addresses or Slack channels. There is also a public-facing GSA staff directory that you can link to.
    • Information that is already well-covered on GSA InSite - link there instead of reproducing it.
    • Specific TTS org chart info (such as lists of names of supervisors and facilitators). Link to the TTS org chart, the 18F org chart, or the Solutions org chart instead.

Choosing a development environment

The first choice you need to make is whether you want to update the Handbook from within GitHub or if you want to download it to your local computer and update it there. The one you choose is your "development environment." You are not locked into an environment – you can choose whichever is more appropriate for each update you want to make, switching back and forth as needed.

GitHub

Using GitHub means you don't need to download or install anything, which is very convenient. For small updates, such as changing some text on a single page, working in GitHub is often easier and faster. Making changes directly in GitHub becomes a little more difficult as you increase the number of pages that you are working with.

Consider using GitHub as your development environment if your proposed changes are fairly simple: adding a single new page or updating content on a small number of existing pages. But if you are working across many pages, working in GitHub may make it more difficult.

If you choose GitHub, you can check the Editing in GitHub page for more information about how to make your edits and submit them for review.

Local

A local development environment requires that you have a text editor installed, have , external,configured your GitHub account with an SSH key, and configured your local git installation. These requirements are only necessary the first time, so while they do introduce complexity, it is only a one-time cost.

Working locally also allows you to build and run the Handbook on your own computer so you can see your changes live in your web browser as you make them, which is especially helpful for larger updates. However, this requires that you either have Docker or Node.js installed and running, additional one-time complexities. Installing those is beyond the scope of this guide for now.

Consider working locally if you are making extensive changes that are worth the time and effort to install a text editor and configure your local git. For more information about working locally, see the editing locally page.

Making your updates

The Handbook is mostly authored in a markup language called Markdown. If you're unfamiliar with Markdown, the , external,Markdown Tutorial is a fun way to learn the basics. If you already know Markdown and just want to brush up on the syntax, the , external,CommonMark reference is a big help.

Find the page you want to update (or create a new one in the pages directory) and start writing! If you need help, feel free to reach out in , external,TTS-only, #tts-handbook. When you're happy with your changes, open a pull request so someone else can review them and get them merged into the Handbook.

The Handbook has a variety of utilities available to make updates easier and help keep everything consistent across pages. There are two primary kinds of utilities:

• Front matter - This is data that you can supply at the top of your page that can change or control how the page is displayed in a web browser.

• Shortcodes - These are small snippets that replace one kind of content with another. For example, the Slack link above was created with this shortcode:

  {% slack_channel "tts-handbook" %}
  

• Components - These are larger pieces of UI that you can add to your page in a consistent way, including alerts, side navigation, or links to more information.

Pull requests (PRs)

Each pull request should be reviewed by at least one other TTS staff member before merging. Once a PR is approved, anyone can merge it (including the original submitter).

If you make a pull request that's best reviewed by a specific person, tag or assign it to that person. It can also help to ping them in Slack to ask for review.

CODEOWNERS

The TTS Handbook uses the GitHub , external,"code owners" feature to automatically add content owners as a reviewer. This means that in most cases, you as a contributor should not need to manually add anyone for a review.

If you suspect that the wrong team was added as a reviewer, feel free to open a pull request to change the CODEOWNERS file, located at the top level of the project.

How to review and merge pull requests

Any TTS staff member can review a pull request. If it's not your area of expertise, ask somebody who has expertise in that area (for instance, by commenting to tag a person or sharing the PR in Slack). If the author of the pull request added a specific person as a reviewer, hold off merging the pull request until at least one specified reviewer has had a chance to review it.

A note to submitters: If you need multiple people to see your PR before it's merged, please add a comment letting reviewers know!

If you're not sure, ask for a second opinion in , external,TTS-only, #tts-handbook first.

Content and accessibility

The handbook follows the , external,18F content guide, and all content should follow web accessibility best practices. Remember to use , external,descriptive link text.

File/folder structure

New files should be created in the pages directory and in the sub-directory that makes the most sense for your content. For example, a new page on an 18F process should go in the pages/18f directory.

Images that should appear in the Handbook should be placed in the _img directory. You can create addition subdirectories and nest them however you need within the _img directory. Use the image shortcode to ensure your images are available on the web after publication.

If you need to include a file for visitors to download, those files should go in the downloads directory. These may also be in subdirectories. Use the download shortcode to ensure the files are published to the web.

Public domain

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the , external,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 copyright interest.