A Digital Servant's Guide to U.S. Federal Information Technology Law and Policy
Joining the United States federal civil service can be daunting, particularly for technology professionals who have not navigated the intricacies of government policy before. This guide is a very brief introduction to key laws, policies, and guidance surrounding the practice of information technology in government.
This guide should not be considered official guidance itself, but rather a tool to guide the reader to official sources. This guide should also not be considered comprehensive, and may not be up-to-date. In all cases, it is recommended that one always consider primary official sources.
If you see something wrong or missing, please do let us know! The easiest way is to just open an issue with your comment or question.
Of course pull requests with direct contributions are always welcome as well!
This is a standard Jekyll / GitHub Pages website. As such, you'll need the comptible version of Ruby installed (2.7.3) via rvm or other means. After that, make sure Bundler is installed, and then bundle install the ruby dependencies as usual.
You probably won't need to install the Javascript/SCSS dependencies as they're statically included in the repo. If you do, you'll need node and either yarn or npm as a package manager, and then simply install as the tool directs from the package.json included here.
There's a couple of helper scripts included in the package.json as well:
-
servewill destroy the local_sitefolder, and then serve the website via jekyll at http://localhost:8000. -
linkpkgwill copy the needed assets fromnode_modulesinto the publicassetsfolder - but again, you should not need to do this step unless you're updating/adding a node package or something.
(I will admit I have yet to find a decent way of including node packages into GitHub pages sites. Here, I've only included the ones needed to compile the SCSS, while the Javascripts are all static copies in the assets folder. I'm open to suggestions here!)
All of the content pages are located in the content/ folder (except the main index.md file, because GitHub Pages wants it at the root.)
We try to strike a balance between creating individual pages for topics and consolidating topics to reduce sprawl. For instance, individual laws only have separate pages if those laws are complicated or span across multiple concerns, such as @FITARA. In other cases, we simply refer directly to the laws in the relevant sections. Laws not related to technology generally won't have their own page unless they are special in some way.
Pages with toc: true in the front matter will automatically create a table of contents at the top of the page when combined with layout: law or layout: document only. This is useful for very long pages.
Browsing through the source, you will find stub pages for content that we have not yet completed. Feel free to add to these as well!
References to laws & policies should generally be linked to official government sources whenever possible. uscode.house.gov is the preferred option for the US Code, www.ecfr.gov for federal regulations, congress.gov for laws, whitehouse.gov for federal policies/executive orders, and so on.
To reduce duplicative references, this website uses a series of data files that provide tagged acronyms that are replaced wherever they appear on the site. For instance, using @FITARA will expand the first reference on a given page to The Federal Information Technology Acquisition Reform Act (FITARA) with a link to the /aws/fitara/ page. Subsequential refernces to @FITARA will retain the acronym and still provide a link. Acronyms without links simply use the <abbr> tag to provide hover-state titles that expand the definition after the first reference on a page.
Additionally, there are a handful of special icons (we call them "glyphs") that can be used, including @SOAPBOX and @WARNING for a megaphone or caution sign respectively.
The _data directory contains all of these files. For instance, the blob/ghpages/_data/acronyms/laws.yml file lists commonly referenced laws and policies. These files are processed on page content via the processing directives found in _includes/filters. This uses standard Jekyll/Liquid tags, no plugins needed!
Since these terms are replaced in the order they are listed in the data files, to avoid conflicts longer terms should be put before shorter terms; for instance DOEd should be listed before DOE to avoid replacing the latter first with the wrong term.
If you're adding new acronyms you typically need to restart jekyll between edits, as these are processed when the site is rebuilt.