diff --git a/.cspell.json b/.cspell.json index eaa3fc6a..41dc02ae 100644 --- a/.cspell.json +++ b/.cspell.json @@ -9,6 +9,7 @@ "CISA", "CISO", "DATAMGT", + "Decap", "DEIA", "FASC", "FISMA", diff --git a/docs/architecture/decisions/0010-replace-yaml-with-markdown.md b/docs/architecture/decisions/0010-replace-yaml-with-markdown.md new file mode 100644 index 00000000..6884bf6e --- /dev/null +++ b/docs/architecture/decisions/0010-replace-yaml-with-markdown.md @@ -0,0 +1,78 @@ +# 10. Replace YAML with Markdown for Job Postings + +Date: 2024-11-27 + +## Status + +Accepted + +## Context + +Job postings by the TTS Talent Team are stored as files in the repository; each +file represents a single job posting. + +Each job posting has a variety of commonalities, such as the salary rate (GS +level), when the job posting opens, when the job posting closes, etc.. We need +to be able to utilize those data not only to render job postings to job seekers, +but also determine the state of each job posting (i.e., if the current date is +before the opening date, the posting is "upcoming" while if the current date is +after the closing date, the posting is "closed"; otherwise, the posting is +considered "open."). + +Previously, each job posting was a single Markdown file that contained some +YAML front matter that included some of these fields. Some of the fields would +be shown elsewhere in the posting (e.g., `{{ variable }}` in the Markdown) +while others were used elsewhere. + +As a result, the editing process for a job posting involved copying a starting +template, filling in various fields in the YAML front matter, and editing the +Markdown to display the needed data. Changing the presentation for how job +postings were rendered required editing every job posting. Data entered +free-form was often not parsable because, generally, Markdown would accept +values that were incompatible with how we were using them. For example, a +Markdown file could say that a job opened on `Monday, November 25th, 2024` and +it would render as-expected; however, the logic for determining the status of +the job would fail. + + +## Decision + +The team decided to transition from job postings being individual Markdown +files with some YAML front matter to having all job postings use only YAML +front matter. This would allow us to use standard templates that would be +consistent in their presentation while also validating the data against a +known schema. + +## Consequences + +Job postings are much smaller and straight-forward as there's less commentary, +instructions, and redundant text in the posting -- there's just the YAML. + +Rendered job postings are more uniform and consistent. + +Automation (e.g., time-based state determination and relevant information +sessions) becomes possible and consistent. + +Data that can be determined or derived (e.g., salary ranges from GS levels) +are simplified (e.g., we can just say `salary: gs-15` and have the system +determine the actual dollar amounts). + +Job posting content is expressed in YAML which is more sensitive to and less +tolerant of incorrect spacing and indentation. + +Invalid Markdown will still be rendered, although possibly not as-intended; +invalid YAML front matter causes the page build process to break. + +The job postings will still be in Markdown files (i.e., the filenames end with +`.md`) but the content will be in YAML front matter. Because the extension +of the postings will be `.md`, a Markdown linter will either skip or fail when +scanning the Markdown files and finding only YAML. A YAML scanner would filter +out `.md` files; if a YAML linter scanned a `.md` file and encountered +actual Markdown, the YAML linter would fail. Content other than job postings +is also present in the repository and those non-postings contain actual +Markdown. + +Therefore, it becomes difficult to configure existing tooling to apply YAML +rules to job postings and not non-posting site content. Moreover, editors +will likely treat the job postings as Markdown due to the `.md` filename +extension and not provide tooling or functionality to support YAML editing. diff --git a/docs/architecture/decisions/0011-skip-usajobs-api-integration.md b/docs/architecture/decisions/0011-skip-usajobs-api-integration.md new file mode 100644 index 00000000..93cb0980 --- /dev/null +++ b/docs/architecture/decisions/0011-skip-usajobs-api-integration.md @@ -0,0 +1,61 @@ +# 11. Skip USAJOBS API Integration + +Date: 2024-11-27 + +## Status + +Accepted + +## Context + +USAJOBS.gov provides an API that can be queried for information about open +job postings across a variety of agencies and offices. Most jobs posted to +the TTS site provide links to application forms on the USAJOBS.gov site. + +Positions posted on the TTS site often have a maximum number of applications +that they'll accept. When the number of remaining application slots is +exhausted, the job posting is changed to the "closed" status, typically by +changing the posting's closing date to a date in the past. This involves +editing the posting file, creating a Pull Request (PR) to review the change, +merging the change into the `staging` branch, then creating a second PR to +merge the change from the `staging` branch into the `main` branch. At best, +this takes several minutes; more typically, it can take longer for the reviews +to take place resulting in delays of various lengths. + +It's possible to query the USAJOBS API to determine the number of applications +that will be accepted and, if no more applications will be accepted, +automatically mark the posting as being closed. + +In order to query the USAJOBS API, an authentication key / token must be +included with each API request. Because these requests would be coming from +the user's browser, we would need to pass along the API key to the client in +order to authenticate the request. The API does not accept OAuth or JWT-based +authentication models. + +While the USAJOBS API is able to provide authoritative state information data +for postings (i.e., how many applications will be accepted), the USAJOBS +database does not contain current, TTS-specific information TTS's postings. For +example, a posting may have a title of `Login.gov Data Engineer`, the posting +on the USAJOBS database may only read `Data Engineer` or `Engineer`. The +differences extend beyond job title -- often, the specific requirements, +responsibilities, etc. that need to be posted on the TTS site don't exist in +the USAJOBS database. + +## Decision + +The team has decided that it will be implausible to query the USAJOBS API for +real-time information. The reasoning is two-fold: + +1. challenges in passing the token to the browser safely +2. job posting data on the TTS Website are more current than the USAJOBS API + +## Consequences + +The manual workflow involving multiple levels of review (therefore, multiple +PRs) will still be used. These PR reviews need to be made by developers on +the TTS Website development team; therefore, the resultant dependency has the +potential to cause delays in an otherwise time-sensitive process. + +Between when the maximum number of applications is reached and when the change +on the TTS Website goes live, applicants will see on the TTS Website that +the position to which they're applying is still open when, in fact, it is not. diff --git a/docs/architecture/decisions/0012-forgo-decap-cms-netlify.md b/docs/architecture/decisions/0012-forgo-decap-cms-netlify.md new file mode 100644 index 00000000..9bc6058e --- /dev/null +++ b/docs/architecture/decisions/0012-forgo-decap-cms-netlify.md @@ -0,0 +1,40 @@ +# 12. Forgo Decap CMS / Netlify + +Date: 2024-11-27 + +## Status + +Accepted + +## Context + +Searching for an easier way to support editing job posting pages on the TTS +Website, we looked into supporting Decap CMS (formerly known as Netlify). + +Decap CMS is a JavaScript-based tool that provides a What You See Is What You +Get (WYSIWYG) experience similar to WordPress or Drupal but without a +server-side component. Decap runs entirely in the browser itself with the +content stored in a GitHub repository as Markdown content. It would be a +bolt-on experience that would integrate directly into our existing workflow +and repository. + +The primary driver in researching additional tooling (i.e., Decap CMS) is to +reduce the complexity associated with editing job posting data. + +Job postings are represented as individual Markdown files that contain solely +YAML front matter. Decap CMS is able to support this in both "Markdown" and +"Rich text" modes; however, Decap doesn't provide any additional functionality +in those situations -- it identifies that the content is YAML front matter and +that's all. This represents a step back from GitHub's web UI because GitHub +can scan YAML front matter and identify invalid YAML whereas Decap just ignores +it. + +## Decision + +The team has decided not to pursue Decap CMS at this time. + +## Consequences + +There is little to no additional value in adding Decap CMS to the mix at this +time. The use-case we're trying to address is actually handled less well as +compared to the existing processes.