NMFS-RADFish · theangchen · Dec 12, 2024 · Dec 10, 2024
diff --git a/docs/developer-documentation/concepts/offline-first.md b/docs/developer-documentation/concepts/offline-first.md
@@ -1,7 +1,8 @@
 ---
 sidebar_position: 2
 ---
-#Offline-First
+
+# Offline-First
 
 Offline-first design prioritizes web app functionality even without internet connectivity. This means building the app so users can interact with it uninterrupted, even without a stable network. 
 

diff --git a/docs/developer-documentation/technical-decision-log/dexie.md b/docs/developer-documentation/technical-decision-log/dexie.md
@@ -4,10 +4,13 @@ description: Simplifies working with IndexedDB
 ---
 
 # Dexie for Offline Data
+[Dexie](https://dexie.org/) simplifies working with IndexedDB.
 
-- **Why we chose this:** Dexie simplifies working with IndexedDB, crucial for RADFish applications that require robust offline capabilities. This aligns with the need for reliable data storage and retrieval in environments with intermittent connectivity.
-- **Trade-offs:** Using a wrapper around IndexedDB like Dexie abstracts some low-level control but significantly eases development complexity, making it a worthwhile trade-off for enhancing offline experience in RADFish applications.
+## Why we chose this 
+Dexie makes IndexedDB development less complex. IndexedDB is crucial for RADFish applications that require offline capabilities. RADFish apps need reliable data storage and retrieval with intermittent internet connectivity. 
 
-LocalForage and PouchDB are alternatives that offer similar abstraction over IndexedDB with additional features like automatic synchronization with remote databases. However, Dexie's simpler API and focus on IndexedDB specifically make it more suitable for RADFish's client-side DB needs.
+## Trade-offs
+Using a wrapper around IndexedDB like Dexie abstracts some low-level control. However, it significantly eases development complexity, making it a worthwhile trade-off.
 
----
+## Alternatives
+[LocalForage](https://github.com/localForage/localForage) and [PouchDB](https://github.com/pouchdb/pouchdb) are alternatives that offer similar abstraction over IndexedDB. They offer additional features like automatic synchronization with remote databases. However, Dexie's simpler API and focus on IndexedDB make it more suitable for RADFish's client-side DB needs.
diff --git a/docs/developer-documentation/technical-decision-log/index.mdx b/docs/developer-documentation/technical-decision-log/index.mdx
@@ -4,8 +4,9 @@ sidebar_position: 6
 
 # RADFish Technical Decision Log
 
-{/* Write top text here */}
+This section provides justification for the technologies and frameworks we chose for RADFish. Most pages include "Why we chose this", "Trade-offs", and "Alternatives" sections. These demonstrate pros, cons, and other options that were considered, respectively.
 
+For more information about this section, read the [statement of purpose](https://nmfs-radfish.github.io/radfish/developer-documentation/technical-decision-log/purpose).
 
 ```mdx-code-block
 import DocCardList from '@theme/DocCardList';

diff --git a/docs/developer-documentation/technical-decision-log/jsdocs.md b/docs/developer-documentation/technical-decision-log/jsdocs.md
@@ -3,13 +3,15 @@ sidebar_position: 8
 description: Accessible and easy to adopt
 ---
 
-# JavaScript w/JS Docs
+# JavaScript with JSDoc
 
-- **Why we chose this:** JavaScript, complemented by JS Docs, offers broad accessibility and ease of adoption for government contractors. This choice supports RADFish’s goal of standardizing frontend development without imposing the stricter typing system of TypeScript, balancing flexibility with documentation needs.
-- **Trade-offs:** The absence of TypeScript’s compile-time type checking increases reliance on runtime testing. However, for RADFish’s diverse and evolving project requirements, JavaScript’s flexibility is more beneficial, allowing for broader adoption among government contractors.
+[JSDoc](https://jsdoc.app/about-getting-started) is an automatic API documentation generator. 
 
-TypeScript provides static typing out of the box, offering compile-time type checking and reducing runtime errors. However, adopting TypeScript involves a steeper learning curve and potentially longer development times. Given RADFish's emphasis on ease of adoption and the existing familiarity within the developer community with JavaScript, JS Docs offers a balanced approach, providing some benefits of TypeScript without its overhead.
+## Why we chose this 
+JavaScript offers broad accessibility and ease of adoption for government contractors.  Combined with JS Docs, this helps standardize frontend development. JavaScript’s flexibility allows for broader adoption among government contractors. It also adapts to RADFish's diverse and evolving project requirements. JS Docs also doesn't impose the stricter typing system of TypeScript. 
 
-Additionally, TypeScript can always be leveraged by teams that wish to use it as migrating from JS to TypeScript is relatively straightforward and there are tools available to automate this process.
+## Trade-offs
+TypeScript provides static typing, offering compile-time type checking, which reduces runtime errors. The absence of TypeScript’s compile-time type checking may increase reliance on runtime testing.  However, adopting TypeScript involves a steeper learning curve and potentially longer development times. RADFish leverages most developers' familiarity with JavaScript. JS Docs offers a balanced approach, providing some benefits of TypeScript without its overhead.
 
----
+## Alternatives
+[TypeScript](https://www.typescriptlang.org/) can still be adopted by teams that wish to use it. Migrating from JS Docs to TypeScript is relatively straightforward. There are tools available to automate this process.
diff --git a/docs/developer-documentation/technical-decision-log/mock-service-worker.md b/docs/developer-documentation/technical-decision-log/mock-service-worker.md
@@ -4,10 +4,13 @@ description: Required for offline functionality
 ---
 
 # Mock Service Worker
+[Mock Service Worker (MSW)](https://mswjs.io/) simulates API responses during development and testing. 
 
-- **Why we chose this:** RADFish's requirement for offline functionality makes Mock Service Worker (MSW) invaluable for simulating API responses during development and testing. This allows developers to build and test applications without dependency on real backend services, crucial for offline-capable applications and for developing apps without a backend to test against.
-- **Trade-offs:** Relying on MSW for development might mask integration issues with actual backend services if human error is made in the setup of MSW and a real endpoint is overridden by the mock endpoint. Nonetheless, the benefits of seamless offline development and testing are crucial for RADFish's goals.
+## Why we chose this
+NOAA applications must work offline. MSW lets developers build and test applications without dependency on real backend services. This helps develop applications with offline functionality without a backend to test against.
 
-JSON Server or Mirage JS provide similar mocking capabilities with more emphasis on full-fledged backend simulation. However, MSW's integration with service workers and its ability to intercept network requests at the browser level offer more realistic testing scenarios for RADFish's offline functionality, making it preferable despite JSON Server or Mirage JS's ease of setup for simpler backends.
+## Trade-offs
+Relying on MSW for development might mask integration issues with actual backend services. For example, an error in MWS setup could result in a real endpoint being overridden by the mock endpoint. However, the benefits of offline development and testing are crucial for RADFish's goals.
 
----
+## Alternatives
+[JSON Server](https://www.npmjs.com/package/json-server) or [Mirage JS](https://miragejs.com/) provide similar mocking capabilities. They emphasize full-fledged backend simulation. They emphasize full-fledged backend simulation and ease of setup for simpler backends. However, MSW's integrates with service workers and can intercept network requests at the browser level. These features offer more realistic testing scenarios for RADFish's offline functionality. 
diff --git a/docs/developer-documentation/technical-decision-log/prettier.md b/docs/developer-documentation/technical-decision-log/prettier.md
@@ -3,11 +3,15 @@ sidebar_position: 7
 description: Ensures consistent code quality and style
 ---
 
-# Prettier/ESLint
+# Prettier and ESLint
 
-- **Why we chose this:** Consistency in code quality and style is crucial for collaborative projects like RADFish. Prettier and ESLint automate formatting and linting, ensuring code adheres to best practices and is accessible to all developers working on NOAA projects.
-- **Trade-offs:** Enforcing a specific coding style may require initial adjustments for developers. However, the long-term benefits of maintainable and error-free code outweigh these adjustments. Also, these standards can be enforced automatically via code editor configuration setups eg. the “on-save” linting of VSCode.
+[Prettier](https://prettier.io/) is an automatic code formatter. [ESLint](https://eslint.org/) analyzes code to find problems and errors in a process known as _linting_. 
 
-TSLint (now deprecated in favor of ESLint) and Stylelint are alternatives focused on TypeScript and CSS, respectively. While they offer specialized linting capabilities, the combination of Prettier and ESLint covers a broader range of RADFish's code quality needs across JavaScript and styling with a unified setup, making them more suitable than using separate tools for different languages.
+## Why we chose this
+Consistency in code quality and style is crucial for collaborative projects like RADFish. Prettier and ESLint automate formatting and linting. This ensures all code adheres to best practices and is accessible to all developers working on NOAA projects.
 
----
+## Trade-offs 
+Enforcing a specific coding style may require initial adjustments for developers. However, the long-term benefits of maintainable and error-free code outweigh this adjustment period. Also, these standards can be enforced automatically via code editor configuration setups. For example, developers can use the the “on-save” linting of VSCode.
+
+## Alternatives
+[TSLint](https://palantir.github.io/tslint/) (deprecated in favor of ESLint in 2019) and [Stylelint](https://stylelint.io/) are alternatives to ESLint. They focus on on TypeScript and CSS, respectively. While they offer specialized linting capabilities, the combination of Prettier and ESLint covers a broader range of RADFish's code quality needs. Prettier and ESLint provide JavaScript styling and linting with a unified setup, making them more suitable than using separate tools for different languages.
diff --git a/docs/developer-documentation/technical-decision-log/purpose.md b/docs/developer-documentation/technical-decision-log/purpose.md
@@ -5,8 +5,14 @@ description: Provides clarity around technical decisions
 
 # Purpose
 
-In order to provide transparency and clarity around the technical decisions we have made, we wanted to provide a technical decision justification for the chosen technologies and frameworks of RADFish.
+This section provides justification for the technologies and frameworks we chose for RADFish. This provides transparency and clarity around the technical decisions we have made.
 
-Each technology and framework selected for RADFish aims to create a cohesive, efficient, and compliant environment for developing NOAA's frontend applications. The choices reflect a balance between ease of use, compliance with federal standards, and the unique operational requirements of NOAA applications, such as offline functionality and support across a myriad of devices. The chosen stack is designed to optimize developer productivity, application performance, and user experience within the context of NOAA fishery reporting programs.
+NOAA's frontend applications have unique requirements, such as:
+
+- **Offline functionality.** Our users do not always have reliable internet access. Our applications must work offline.
+- **Cross-platform performance.** Our applications must work on both mobile and desktop devices. They must work on a variety of operating systems and browsers. 
+- **Regulation compliance.** Federal web applications must meet regulation standards, such as 508 Compliance.
+
+Our choices must balance ease of use for our developers while meeting these challenges. We selected technologies and frameworks to create a cohesive, efficient, and compliant environment. The chosen stack optimizes developer productivity, application performance, and user experience. 
 
 ---
diff --git a/docs/developer-documentation/technical-decision-log/tanstack.md b/docs/developer-documentation/technical-decision-log/tanstack.md
@@ -3,7 +3,11 @@ sidebar_position: 11
 description: Offers flexible state management
 ---
 
-# Tanstack for State Management
+# TanStack for State Management
+[TanStack](https://tanstack.com/) provides utilities for state management, tables, and querying.
 
-- **Why we chose this:** Tanstack (React Query and React Table) offers efficient solutions for managing server state and table state in RADFish applications. This is particularly useful for handling NOAA's complex data structures and multi-entry forms, providing an improved user experience with less boilerplate code.
-- **Trade-offs:** The adoption of Tanstack requires familiarity with its API and concepts, which may present a learning curve. However, the productivity gains and enhanced user experience in handling NOAA’s data-centric applications make it a great choice for RADFish's goals.
+## Why we chose this 
+TanStack helps manage server state and table state in RADFish applications. NOAA applications have complex data structures and multi-entry forms. TanStack creates an improved user experience with less boilerplate code.
+
+## Trade-offs
+Using Tanstack requires familiarity with its API and concepts, which may present a learning curve. However, it handles NOAA’s data-centric applications and provides an enhanced user experience.
diff --git a/docs/developer-documentation/technical-decision-log/trussworks.md b/docs/developer-documentation/technical-decision-log/trussworks.md
@@ -5,9 +5,13 @@ description: Adherence to US Web Design Standards
 
 # Trussworks Component Library
 
-- **Why we chose this:** Trussworks Component Library’s adherence to USWDS ensures RADFish applications meet federal standards for accessibility and design. This alignment with NOAA’s branding guidelines and 508 compliance requirements makes it a strategic choice.
-- **Trade-offs:** The use of a specific component library might restrict design flexibility. However, the consistency and compliance it brings to RADFish applications are invaluable, especially for government projects.
+The [Trussworks component library](https://github.com/trussworks/react-uswds) is a set of standard components from React libraries and the [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/).
 
-Material-UI and Ant Design offer extensive component libraries with customizable themes. However, Trussworks' specific focus on USWDS compliance and its integration with React makes it a better fit for RADFish, despite the broader design options available in Material-UI or Ant Design
+## Why we chose this 
+Trussworks component library adheres to USWDS standards. This ensures RADFish applications meet federal standards for accessibility and design. It also aligns with NOAA’s branding guidelines and 508 compliance requirements.
 
----
+## Trade-offs 
+Using a specific component library might restrict design flexibility. However, using a single component library provides consistency. Trussworks also meets compliance standards, which is invaluable for government projects.
+
+## Alternatives
+[Material-UI](https://mui.com/material-ui/) and [Ant Design](https://ant.design/) offer extensive component libraries with customizable themes. These provides broader design options. However, Trussworks' specific focus on USWDS compliance and its integration with React makes it a better fit for RADFish. 
diff --git a/docs/developer-documentation/technical-decision-log/workbox.md b/docs/developer-documentation/technical-decision-log/workbox.md
@@ -4,8 +4,10 @@ description: Service worker management for improved caching
 ---
 
 # Workbox
+[Workbox](https://developer.chrome.com/docs/workbox) is a collection of service worker libraries and tooling.
 
-- **Why we chose this:** Workbox streamlines service worker management and offline capabilities essential for RADFish. It simplifies caching strategies and offline data handling, critical for NOAA PWAs used in an offline fashion.
-- **Trade-offs:** Workbox’s abstraction layer may obscure some of the finer details of service worker implementation. However, the ease of integrating robust offline functionalities justifies its use within RADFish. The ease of implementation also makes the service worker functionality more approachable for cases where NOAA developers need to modify the RADFish-provided setup.
+## Why we chose this
+Workbox streamlines service worker management and offline capabilities essential for RADFish. It simplifies caching strategies and offline data handling. This is critical for NOAA PWAs used offline.
 
----
+## Trade-offs
+Workbox’s abstraction layer may obscure some of the finer details of service worker implementation. However, the ease of integrating robust offline functionalities justifies its use within RADFish. The ease of implementation makes it more approachable for NOAA developers. Developers can easily modify the RADFish-provided setup as well.