gsa / 10x

[Deprecated] Website for the Office of Investments in GSA’s Technology Transformation Service

10x Website

Content management

This site uses Netlify CMS for managing content edits. You can access the content management editor by going to the site's domain, followed by "/admin". It's best to make significant changes on the Demo version of the site, which is at https://demo.10x.gsa.gov. Although the admin site is available in production, it is unwise to make changes to the live site.

To edit the content on the site, log into the content manager at https://demo.10x.gsa.gov/admin using your GitHub credentials.

For detailed information about how to use the content manager, check out the content authoring guide at https://docs.google.com/document/d/10VRGLNhSkWqjQdHAe10RXKaI9qdL79CLW3I4-WlPz7E/view

To save your changes and see them on the demo site, click the "Publish" button at the top right of the editor. Each publish will start a new build in Federalist and should take up to 5 minutes to deploy. You will not receive a notification when it succeeds, but you can monitor build status here.

When you're satisfied with how the demo site looks and want to push your changes live, you should open a Pull Request from the demo branch to Main.

If possible, invite someone to review your changes.

When you're ready, approve and merge the request, but do not delete the "demo" branch.

---

Development

Installation & getting started

This site can be run locally using NodeJS. Using the command line, install the site and dependencies:

npm i

Then add a .env file with the BASEURL variable equal to your localhost or the production domain (feel free to use .env.local and .env.production if you like):

BASEURL=https://10x.gsa.gov
PUBLIC_URL=$BASEURL

Also, the current build is very tempermental and will only work on specific versions of node and npm. Make sure you're using node v16.15.0 and npm v8.5.5 in the project directory.

nvm install 16.15.0
npm install -g [email protected]

To serve the site locally:

npm run start

To build for production:

npm run federalist

Technical information

This site is a small custom React app. Many of its components are based on the USWDS. The data and contents of the site are in JSON files, which is best authored and edited through the Netlify CMS admin; however, you can edit the JSON locally and re-start the start task to test changes to the data model or content.

10x's Issues

Identify technical or logistical challenges that might take awhile to resolve

scratch pad – what we know so far

• set up web hosting (IP address) - #10
• Get the subdomain 10x.gsa.gov – could take two months - #9

it's done when

• issues are created for each task in the backlog

Wireframe the things

it should include …

• quick overview of 10x
• etc etc.

it's done when …

• thing
• and another thing

phases

• content
• wireframing/iA
• give it a look and feel
• translate into code
• testing
• push to live site
• rapid validation / usability testing

Create high level information architecture diagram

Onboarding Ryan/Offboarding Cordelia

this should include …

• @RyanSibley added to the GitHub repo as a collaborator
• she's able to get the local install up and running
• invited to all the website team meetings - @willcahoe
• update her on where the content is right now - @willcahoe and @thebestsophist
• walk her through the framing docs created so far - @thebestsophist
• add to Mural room
• add to Team Drive in Google Drive

it's done when

• @RyanSibley agrees it's done

Review all the work done so far on the website and assess current state

it should include …

• critiquing the current designs/content
• talk to Dan-O about his sketches
• convert raw notes from critique to something sensible

it's done when …

• we have a document that makes sense of that feedback in terms of design principles or directions to move in, and is posted publicly, probably on the wiki

Write a quick 'getting started' guide and add it to the readme

it should …

• include very simple, all inclusive (aka starting from scratch) step-by-step instructions on how to run the site locally
• follow (relevant) best practices described in https://open-source-guide.18f.gov/making-readmes-readable/

it's done when …

• instructions are added to the Readme.
• Carolyn is able to remember how to do it after a week or so away from the project, which is a pretty good approximation for someone starting from scratch.

Onboard Shawnique

this should include …

• Shawnique is added to the GitHub repo as a collaborator
  - [ ] she's able to get the local install up and running
• able to access the information architecture and storyboarding roadmap
• invited to all the website team meetings
• update her on where the content is right now - @willcahoe
• walk her through the framing docs created so far - @willcahoe
• add to Team Drive in Google Drive

it's done when

• Shawnique agrees it's done

Create eligibility section (who is eligible and what ideas can be submitted)

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

phases

• content
• wireframing/iA
• give it a look and feel
• translate into code
• testing
• push to live site
• rapid validation / usability testing

visual design of the content

it should include …

• responding to content feedback
• assure all necessary pages are designed and consistent
• all design elements function properly (buttons work, nav works, links work, etc)
• creating/collecting any illustration as necessary
• getting feedback from stakeholders on major changes
• documenting any citations/sources for imagery

it's done when …

• the site works and looks complete at all responsive widths
• the team agrees that it addresses user feedback adequately
• the work passes Lighthouse audits with as close to straight 100s as possible

code the thing

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

phases

• content
• wireframing/iA
• give it a look and feel
• translate into code
• testing
• push to live site
• rapid validation / usability testing

Create project brief and add it to readme.md

The initial project brief should give newcomers everything they need to know to understand what this project is and why we're doing it.

it should include ...

• problem statement (what problem does the website solve?)
• project goal
• primary user groups, ranked

it's done when ...

• the team and stakeholders agree on it
• it's entered into the readme.md and merged to the master branch

Plan some website activities for 10x IRL

Maybe week of March 19

Add user promises, and signals/metrics to project brief

it should include …

• primary user promises, ranked
• what action we want users to take after visiting the site
• first stab at signals/metrics that the site is working for users

it's done when …

• the team and stakeholders agree on it
• it's added to the readme.md file and merged to master

dependent on

• #2 create project brief

Register sub-domain 10x.gsa.gov

to do

• We can keep the site on a Federalist preview URL till we have a version of the site that we are comfortable pushing live (or semi-live). This is probably the easiest path to take.

• We can get the 10x.gsa.gov URL now,

• but we'd have to make master into a locked branch that includes just a splash page on the site, "10x is coming soon! 🎉". This way anyone coming to the site would see the splash page.

• Then we'd create a demo branch where we'd do our development work. The pages/previews for this would live at demo.10x.gsa.gov and would only be visible to people who have the link. Robots would not know about it.

dependent on

• #10 - set up web hosting

Note

@willcahoe started this process awhile ago and it got stuck, seems we need an IP address before we can create the subdomain.

write the content for "i'm thinking about pitching an idea" section

it should …

• pull from existing 10x content (esp. what the writing lab has already reviewed)

it should include (not in order) …

• Eligibility information (people and ideas) in encouraging language
• information about what a TTS sponsor is and how to get one
• short list of previous pitches that have been approved
• what makes a good pitch
• sample pitch
• show criteria for scoring
• how to ask for help in creating your pitch
• examples of successful projects that have gone through the system (short list)

it's done when …

• the team has agreed upon the content and there are no more comments/suggestions in the doc
• the content is ready to be used in wireframes/mock ups

Add uswds alpha 2 and gulp pipeline

it should include …

• add USWDS standard components sass
• add USWDS alpha 2.0 prototyping and production utilities sass
• add USWDS settings overrides
• add gulpfile to process these sass files with overrides
• test that it all works with a sample page

it's done when …

• a sample page can access the final, custom, USWDS css
• i've documented how this is set up in README.md (or elsewhere in the github root)

Create a roadmap

it should include …

• user promises, prioritized and/or in sequence
• break down the top priority user promise into features the team can work on (this can be broken down further in sprint planning/backlog grooming/breaking down the work meetings on an ongoing basis)
• more loosely define some of the work that needs to be done on second priority user promise

it's done when …

• the team and stakeholders have agreed on the roadmap
• it's published on the GitHub repo in the Readme file.

Research options for allowing federal employees to submit ideas online

it should include …

• a way to restrict submissions from .gov or .mil addresses

it's done when …

• we pick a course of action and create a card for it

Create rough content structure for financials section

it should include …

• Explain the funding authority of the DSF
• Simplified breakdown of DSF spending from the previous year (p. 3 YIR)
• DSF spend plan for current FY and upcoming FY
• List of successful projects (and the impact they have created) (pg 5 - YIR)
• Brief description of projects funded (not just titles)
• Show funnel and why it's a good thing in terms of exploring ideas + cost avoidance
• Provide PDF of 10x Year in Review
• Contact info for more information

it's done when …

• we have a rough outline of the content structure

Gather current metrics

In order to know if the website is actually benefiting the 10x program, we need some metrics. More specifically, we need to know what the current state is so we have something to compare against.

it should include …

• Number of pitches for Phase 1 funding from previous rounds
• Number of pitches for Phase 1 funding that list other agencies as SMEs (submitted through a TTS sponsor)
• Number of different agencies represented as SMEs on pitches for Phase 1 projects (for example, if pitch 1 has NIST as a SME and pitch 2 also has NIST as a SME, we'd only count NIST once. This is more about breadth than quantity).
• Count of inquiries from other agencies on how to set up a 10x-style program (if this is info we can gather, if not we may have to leave it out for now. It probably will take some creative email mining).
• Count of consulting engagements with other agencies on running or setting up a 10x-style program

it's done when …

• We have a spreadsheet where these numbers are tracked that the entire team can access.
• (probably) those metrics are also public on the repo

outstanding questions

• do we only want to track Phase 1 or do we want to track later phases as well?

Quick overview of the 10x program

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

phases

• content
• wireframing/iA
• give it a look and feel
• translate into code
• testing
• push to live site
• rapid validation / usability testing

Research what required statements we need to include in the footer

it should consider …

• whether we need ones that are separate from the overall gsa.gov site
• Privacy, FOIA, Accessibility, any other required links, etc.

it's done when …

• we've reached a yes/no conclusion on each one
• if yes, we've created issues to account for the work of creating them.

Integrate DAP into website

it should include …

• reach out to Tim Lowden

it's done when …

• the DAP code snippet is on demo (and maybe prod?)
• we have a link to view the Google Analytics for our site saved somewhere convenient

Add submission timelines

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

phases

• content
• wireframing/iA
• give it a look and feel
• translate into code
• testing
• push to live site
• rapid validation / usability testing

mood boards and methodological approach to visual style

it should include …

• At least two collections of mood boards / style tiles in Invision or elsewhere
• These should collect colors, type, images, and combinations that suggest a tone and visual direction

it's done when …

• We've discussed these deliverables with our project stakeholders
• Iterated on the deliverables if necessary
• Agreed/decided on a direction

Create a simple splash page to point URL to

need this for #9

it should include …

• 10x blurb
• something about this coming soon, but not like in a lame way
• contact information [email protected]

it's done when …

• it's on master and you can view it via https://federalist-proxy.app.cloud.gov/site/gsa/10x/

Create a "what makes a good pitch" section (what makes a good pitch, examples, timelines, guidance)

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

Write the "I'm pitching an idea" content

it should include …

• how to submit an idea
• information about expected phase durations, timelines from previous projects
• information about what kind of commitment/role we expect from submitters
• call for ideas schedule
• how to message the team

it's done when …

• the team has agreed upon the content and there are no more comments/suggestions in the doc

Write/gather/edit content for the overview of 10x

it should include …

• review a number of the overviews of 10x that have already been written
• look at what's on the demo site
• pick or piece together the best one (1-2 sentences)

it's done when …

• the team has agreed upon the content and there are no more comments/suggestions in the doc

Onboard Cordelia

this should include …

• @thebestsophist added to the GitHub repo as a collaborator - @willcahoe
• she's able to get the local install up and running - @thebestsophist
• invited to all the website team meetings - @willcahoe
• update her on where the content is right now - @willcahoe and @carodew
• walk her through the framing docs created so far - @carodew probably
• add to Team Drive in Google Drive

it's done when

• @thebestsophist agrees it's done

Test the Content

it should include …

• Recruit Participants
• Conduct Interviews (Round 1)
• Conduct Interviews (Round 2?)
• Collaborative Synthesis

it's done when …

• The first round of synthesized content is uploaded to the master branch

Github > slack integration test

it should include …

• thing
• and another thing

it's done when …

• it posts to our slack channel

Set up web hosting

This will happen with/through Federalist.

it should include …

• a staging site
• a production site

it's done when …

• we have urls to the staging and production site
• and those URLs are documented, either on this repo and/or in the slack channel (Internal to TTS)

outstanding questions

• still how do we do this? @jeremyzilar can help with this.
• through federalist, for all intents and purposes, using jekyll as the templating language

Create eligibility section (who can submit, what ideas can be submitted)

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

Set up a staging/demo site

it should include …

• a new branch that is named so that it's obviously the staging site
• the demo/staging branch is the default branch for merging PRs
• the master branch is set up as a protected branch
• that branch is set up as the demo branch in Federalist

it's done when …

• opening a PR automatically populates the demo branch as the merge-to branch
• the master branch is set as protected
• we have a working URL for both the live site and the demo branch (via Federalist) and those URLs is included on the front page of this GitHub repo (most typically these are located in the repo description, near the top of the code tab, but could be included in the readme or other appropriate place).

Contact info

it should include …

• contact info / instructions on how to talk to a human about your idea
• general contact info

it's done when …

• thing
• and another thing

Figure out how to set up automatic testing 😅

it should include …

• ping someone in #dev and see if there's someone who can coach us through this
• figure out what Federalist is testing for already (so we don't duplicate)
• talking to someone who knows what they're doing (Circle CI, accesslint?)
• creating clear issues for the work that needs to be done, once we know what that work is

it's done when …

• we know what we need in terms of automatic testing, and that info has been added to #31

Does not include actually setting up the automatic testing, we'll do that in a separate issue.

outstanding questions

• how do we even ...

Write the "I've pitched an idea" content

it should include …

• Information about what happens after you submit
• What happens next (accepted or denied)
• How to edit, amend, or retract an idea
• What phase we're in right now (evaluating, awarded, etc). Note: this content will need to be actively updated by someone.

it's done when …

• the team has agreed upon the content and there are no more comments/suggestions in the doc
• the content is ready to be used in wireframes/mock ups

Create designs/prototypes/concepts for testing (mobile, tablet desktop)

it should include …

• about 10x
• "i'm thinking about pitching an idea" section
• screen sizes from minimum screen size in Definition of Done and max width.

it's done when …

• the team has had a chance to provide feedback and the feedback has been addressed (which can include rejected)
• @thisisdano has what he needs to get crackin' on visual design and code

dependent on

• first draft of content

Add automatic testing into the workflow

TBD – based on what we learn in #28

it should include …

• copy circle.yml from plainlanguage.gov
• install htmlproofer

it's done when …

• Circle CI runs without errors through Circle CI interface
• and it would be super cool if it ran every time you submitted a PR in the GitHub interface but IDK how to make that happen

Clarify what this project team should aim to accomplish in roadmap and elsewhere

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

review / testing

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

phases

• content
• wireframing/iA
• give it a look and feel
• translate into code
• testing
• push to live site
• rapid validation / usability testing

Make a quick overview of the 10x program

it should include …

• thing
• and another thing

it's done when …

• thing
• and another thing

Finish jekyll install

it should include …

• @jeremyzilar takes a machete to the extraneous files we don't need
• pull in the more recent changes from master
• then will submit a PR to master

it's done when …

• jekyll
• is on master
• and is on federalist
• initial scan from W Slack I am not sure this needs to happen yet. This can come later after we have a working prototype

Decide on what 'done' means

This is probably a workshop/collaborative design session where the build team can suss out how done is done. Can probably be combined with #3.

it should include …

• input from everyone who will be involved in building the site
• acceptance criteria that should apply to all issues
• (optional) it might include some quick and dirty design principles, if there's appetite for this

it's done when …

• We document the Definition of Done somewhere publicly available and easy to find. Could be in the readme doc but also could be in the wiki.

test the design

it should include …

• talking to roughly 5-7 people
• research questions and goals

it's done when …

• Team agrees on most important changes to make based on feedback
• we incorporate top recommendations into content and design

Determine artwork needs and collect/create art

• Discuss feedback from content testing with an eye to places art or illustration could resolve issues
• Make a list of art that needs to be created/collected and what that art needs to accomplish
• Find or create art based on those requirements
• Add to the website using contemporary best practices — with an eye to accessibility and speed
• Assure the art is cited and sourced correctly

Add "what makes a good submission" guidance

it should include …

• quick overview of what makes a good pitch
• a sample pitch
• criteria for how pitches are scored
• how to ask for help creating the pitch
• a short list of projects that have made it through the system (e.g. plainlanguage.gov)

it's done when …

• thing
• and another thing

phases

• content
• wireframing/iA
• give it a look and feel
• translate into code
• testing
• push to live site
• rapid validation / usability testing

Create high level IA for the site

it should …

• indicate where all high level sections belong in the iA
• align with how we expect users to flow through the site
• indicates priorities in content/sections

it should include

• Program overview
• eligibility information
• submission guidelines
• how to connect with a useful human

Does not include wireframes or fully fleshed out UI copy.

it's done when …

• the team agrees on the diagram
• diagram is posted in an easy-to-find public place

Decide on team norms and workflow

This is probably a workshop/collaborative design session where the build team can suss out how we want to get things done. Can probably be combined with #4.

it should include …

• input from everyone who will be involved in building the site
• an intro to Kanban (if needed)
• identifying the phases a unit of work needs to go through (not always sequentially but usually so)
• talk about team communication preferences
• how often we need to meet and at what cadence
• discussion on what 'done' is

it's done when …

• The agreed upon phases have been added as columns in the Kanban board ("Project" in GH) in a way the team can agree is sensible and workable
• we have a publicly documented Definition of Done for all work that will end up on the website