18f / handbook

The home of policies and guidelines that make up TTS.

TTS Handbook

The TTS Handbook documents the mission, values, structures, policies, tools, and guides that shape our team. This is a living document and is updated regularly. If you have questions, comments, or suggestions, please open an issue. If you want to add content to the Handbook, please submit a pull request or ask in #tts-handbook.

Note: If you're changing any kind of process, please let #wg-onboarding know so we can keep the handbook, new hire messages, and checklists up to date.

Development

Docker

1. Clone this repo
2. Run docker compose up
3. Open http://localhost:8080

Not Docker

To run the site locally:

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

   npm install
   npm start

3. Open http://localhost:8080

Contributing

If you are interested in contributing to this repository, you can read more at CONTRIBUTING.

Travel guide development

To add additional images:

1. Add an image to the _img/travel directory.
2. Link the image on the travel page, with folding HTML: <img src="{% image "_img/travel/filename.png %}" class="travel-guide-hide">.
3. A show/hide link will automatically be created.

To create a new page:

1. Create a markdown file in the pages/policies/travel directory.
2. Include a title and links to the "Travel Guide TOC" (see existing pages for reference).
3. Update the page content.

• Update the Travel Guide TOC pages/policies/travel/travel-guide-table-of-contents.md with a link to your new page.

Linting

We use Prettier to format Markdown. You can fix your files locally with:

$ npm run lint

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 copyright interest.

handbook's Issues

Clarify procedure for lost PIF card

For the /equipment doc. Victor advised people should fill out the lost access card form (forwarded to @keithrwilson) and email it to [email protected].

Also on Drive: https://drive.google.com/file/d/0B0SnS9Ferbdnc3p6cmdOT05mUGNwdlNLMncxME5VZFlOOFhz/view

Move GSA WiFi and VPN info to a Google Doc

GSA IT (the office of the CISO) has politely requested that we move the info on https://handbook.18f.gov/networks/ to a Google Doc.

I believe we should do this, since we're documenting a system that they (not we) own and operate.

Update from #infrastructure at Fri, 14 Oct 2016 18:36:47 GMT

https://gsa-tts.slack.com/archives/infrastructure/p1476470207002201

Test issue!

Update from #strategy at Wed, 26 Oct 2016 15:23:46 GMT

https://gsa-tts.slack.com/archives/strategy/p1477495426001849

Amber's Test

Update from #calc at Fri, 14 Oct 2016 16:30:20 GMT

https://gsa-tts.slack.com/archives/calc/p1476462620002280

consolidate Google Docs/Drive guidance

There is very little in https://handbook.18f.gov/google-docs/ that is Docs-specific, and therefore we should merge the page into https://handbook.18f.gov/google-drive/. We should also make sure to mention GACA Accounts for sharing outside of GSA.

Mentoring page not showing up on home page

We just recently merged in new content around mentorship, but the link to the new page is not showing up on the main page. I thought that by adding a page in it would be picked up automatically during a rebuild based on how the index page is constructed, but I could be wrong.

Does anyone know if there's something else that needs to be done to have the link appear on the home page?

Replace welcome from Aaron Snow

This is no longer relevant, though I speculate that it contains valuable information. It probably doesn't make sense to remove it entirely—it just needs to be recast for its new context.

Update from #xd-fedesign at Wed, 19 Oct 2016 16:27:11 GMT

https://gsa-tts.slack.com/archives/xd-fedesign/p1476894431000569

Info about getting a "work station eval" for ergonomic issues

https://gsa-tts.slack.com/archives/talent/p1476310364000408

Update from #fec-data at Mon, 31 Oct 2016 18:01:46 GMT

https://gsa-tts.slack.com/archives/fec-data/p1477936906002086

search function is not functioning

Whenever I try to do a search, I get a 404:

404 Not Found

Code: NoSuchKey
Message: The specified key does not exist.
Key: site/18f/handbook/search/index.html
RequestId: F52720F2B3890BFC
HostId: nHhnA+Y+UbyCKPzeymcrEDJ3C/LhS5nJzz/05nScyiEp+i3OCOLIK7V01/jF6xdpvK1RxeoSZbE=
An Error Occurred While Attempting to Retrieve a Custom Error Document

Code: AccessDenied
Message: Access Denied

Others within 18f have been able to reproduce this. Let me know what I can do to help diagnose/fix the issue. Thanks, and have fun!

Bring over any remaining relevant issues from old private repos

We have a number of open handbook issues in our old private repositories: 1 and 2.

We should assess those issues and move over anything that is still important (including consolidating related/redundant issues when possible), and close those issues after we move them.

EAP in Benefits?

I was looking for info on the Employee Assistance Program (https://handbook.18f.gov/employee-assistance-program/) and couldn't find it in Benefits. Fortunately I remembered what it's called, so was able to search it up, but I suggest that it should be listed in Benefits.

Update from #general-talk at Mon, 17 Oct 2016 15:53:13 GMT

https://gsa-tts.slack.com/archives/general-talk/p1476719593005810

Update/Create Employee Express page to include more items to look out for.

As a follow up to the following slack discussions: https://gsa-tts.slack.com/archives/general-talk/p1478007179007423, we may want to invest some time to add content about Employee Express and what different line items to validate as folks have been impacted as part of the onboarding process. Could be an addition to the existing Employee Express section (or new page)

Some things this handbook page may want to include are in this Employee Express content needed document (was unsure what is considered sensitive hence the google doc instead of putting it directly in the issue) Anyone in the 18f-team google group should have edit access to the above doc.

Note: this issue makes the assumption folks have gotten access to Employee Express; it seems there may be some friction points there as well (so perhaps a separate issue is needed to update the Employee Express access section

Update from #identity-dev at Thu, 06 Oct 2016 21:50:29 GMT

https://gsa-tts.slack.com/archives/identity-dev/p1475790629000951

Update from #cloud-gov-support at Thu, 27 Oct 2016 18:24:43 GMT

https://gsa-tts.slack.com/archives/cloud-gov-support/p1477592683003128

Update from #dev at Fri, 21 Oct 2016 17:47:37 GMT

https://gsa-tts.slack.com/archives/dev/p1477072057001255

clarify when new releases of applications need to be approved

https://gsa-tts.slack.com/archives/infrastructure/p1478024437003159

Update from #newcomers at Tue, 18 Oct 2016 15:10:47 GMT

https://gsa-tts.slack.com/archives/newcomers/p1476803447000412

https://docs.google.com/spreadsheets/d/14hEWuhlhKi-EbAFUcy1tuoEejl-7DNiBTI57ZbIQF9w/edit#gid=0

This google doc has instructions on how to request various software. should go into the handbook?

find your timekeeper update for the leave reconciliation feature

Instead of listing the timekeepers at the bottom of the page under the find your timekeeper header, we should link to this sheet. https://docs.google.com/spreadsheets/d/1HQYkVPvKOdzG0lvtcIwR3iEfryPaBktaDYGERqGymoc/edit#gid=0

Update from #incident-response at Mon, 17 Oct 2016 13:53:05 GMT

https://gsa-tts.slack.com/archives/incident-response/p1476712385000793

Update from #admins-slack at Tue, 01 Nov 2016 16:49:51 GMT

https://gsa-tts.slack.com/archives/admins-slack/p1478018991002845

Clarity around being invited to an event

Issue: The handbook doesn't clarify, or make it easy to find, what employees should do when they are invited to government based events, especially those that might occur at the White House.

Proposed Change:
List out the steps an employee should based on the different contexts which one might be invited to an event. Examples include:

• Non-government, public events
• Government, public/private events
• Conferences, online or offline
• Interviews

While the steps for these are effectively the same, calling out the different situations can help folks understand what's expected of them in terms of approvals.

Update from #admins-slack at Thu, 20 Oct 2016 15:06:23 GMT

https://gsa-tts.slack.com/archives/admins-slack/p1476975983002144

Explain default policy for certain software updates (wait for explicit news about approval)

https://gsa-tts.slack.com/archives/tts-cio-collaboration/p1476300054000719

Update MOU sample link on Agreements page

The current MOU sample link provided on the Agreements page is from July 2015 and predates our transition to TTS. As a result, anyone who uses it as a sample will have to alter the language so that it represents our current organizational structure. It would be better to have a more current MOU sample linked to here so less editing is required.

Clarify policy around data/information sent to us by non-18F partners

We want to avoid situations where 18F and GSA are put at risk by receiving data from partners that is marked for public release but is actually not suitable for public release.

@afeld, @brittag, and @wslack jammed on the topic in this google doc for a bit, and aren't certain yet where the updates should go and what the updates should exactly be.

Right now, we are thinking that the information should go on https://github.com/18F/open-source-policy/blob/master/practice.md#protecting-sensitive-information as much as possible, with procedural information on https://handbook.18f.gov/github/#rules as a separate bullet or subbullet of the "no sensitive information" rule.

Add new page for 18F Learn under About Us / Teams

As @fureigh, @jcscottiii, @ctro, myself, and others work on adding a new section and information for mentorship, we realized that we didn't have anything to reference for 18F Learn. As this is one of 18F's primary business units now, it should be front and center with the other parts of the organization!

A new page should be added in the About Us / Team folder containing more information about 18F Learn. It should automatically be picked up and rolled in once it exists so that a link to it appears in the appropriate section of the home page.

Tagging @makeartfromwar, @vicuk, and @ddotrollins on this, even if just for visibility! :-) Are there materials we could pull from to create a new page? Thanks!

Update from #bots at Wed, 26 Oct 2016 21:02:39 GMT

https://gsa-tts.slack.com/archives/bots/p1477515759000234

consolidate Tock guidance

Here are the resources I found (will keep adding to this list):

• https://handbook.18f.gov/tock/
• FY17 rates, policies, and how to Tock your time from @quepol
• FY17 Billing Policies from @hollyallen
• Note from @joshuabailes about travel
• How to Tock if you’re in XD from @carodew
• Tock/billability guidance for 18F Devs from @ertzeid

Would be great to get all of the general-purpose info into the Handbook page.

Update from #general-talk at Fri, 04 Nov 2016 16:13:24 GMT

https://gsa-tts.slack.com/archives/general-talk/p1478276004008176

Update from #incident-response at Mon, 17 Oct 2016 13:52:47 GMT

https://gsa-tts.slack.com/archives/incident-response/p1476712367000792

Out of date Github Link on How We Work/Tools/Github.md#working-with-outside-collaborators

https://github.com/18F/handbook/blob/master/_pages/how-we-work/tools/github.md#working-with-outside-collaborators

It looks like the link on the github support link is out of date on number 4:

• (Ask #admins-github to) create a team whose access we can turn off/on with one button. Separate a staff-only team from a contractor/mixed/collaborator team for a project, and name it something like Project name - Collaborators | Skillset.

Update from #go-cubs at Thu, 03 Nov 2016 03:14:57 GMT

https://gsa-tts.slack.com/archives/go-cubs/p1478142897000871

Update `Salesforce Event Approval` section

...to reflect how to proceed while Pia's on detail.

https://handbook.18f.gov/professional-development-and-training/#make-your-request

Handbook page on slack should specify that all slackbot auto responses must not contain private or sensitive information

This is because public channels and the alumni channel can still access Slackbot auto responses.

Update from #news at Mon, 17 Oct 2016 15:08:00 GMT

https://gsa-tts.slack.com/archives/news/p1476716880000614

Update from #dev at Tue, 08 Nov 2016 19:07:25 GMT

https://gsa-tts.slack.com/archives/dev/p1478632045001815

Include a list of quick fixes to common equipment problems

Maybe this is better handled one such problem at a time, but something that came up yesterday that I hadn't heard in my previous sixteen months at 18F: When you experience one of those intermittent and ongoing audio disappearances, open up the terminal and run sudo killall coreaudiod.

I had to find a similar workaround when my Macbook served me "Bluetooth not available". These kinds of small-scale tech fixes would save us some time. Maybe on the equipment page or maybe linked from it.

add a section about Slack admin responsibilities

• Subscribe to responses for the following forms (screen capture)
  • New user requests (internal)
  • New public user requests (external)
  • Integration requests
• Delegation of functionality

/cc @wslack

Update from #townhall at Tue, 01 Nov 2016 18:43:44 GMT

https://gsa-tts.slack.com/archives/townhall/p1478025824002029

Update from #general-talk at Tue, 01 Nov 2016 20:07:36 GMT

https://gsa-tts.slack.com/archives/general-talk/p1478030856007699

Add a section on Sauce Labs to "Tools"?

We have access to Sauce Labs which is useful for manually and automatically testing that our sites work on browsers that we may not have access to (e.g. Internet Explorer). Since it's useful for manual testing too, it might be appropriate to include in the 18F Handbook rather than one of the guides for engineers, but I'm not sure.

Thoughts?

Highlight links with something more than color

This may not be an issue on all pages, but on some (for example, https://handbook.18f.gov/first-time-travel-travel-card/ ), links are only differentiated from the surrounding text by changing color. This makes the page harder to use and is a 508 violation

See also screenshot. See if you can find the link. Now try it with your screen set to grayscale!

Add where to tock required training

https://handbook.18f.gov/professional-development-and-training/#mandatory-training

Update from #product at Wed, 09 Nov 2016 18:32:27 GMT

https://gsa-tts.slack.com/archives/product/p1478716347001070