Merge pull request #672 from GSA-TTS/671-draft-adrs

.cspell.json

@@ -9,6 +9,7 @@
     "CISA",
     "CISO",
     "DATAMGT",
+    "Decap",
     "DEIA",
     "FASC",
     "FISMA",

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.

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.

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.