Merge pull request #79 from dcgoodwin2112/local-dev-doc-updates

Expand local dev docs. Add contributing page

docs/docs/development/local/contributing.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 3
+title: Contributing
+---
+# Contributing to Performance.gov
+
+This guide outlines the process for submitting changes.
+
+## Contribution Workflow
+
+1.  Fork the project repository
+2.  Checkout the `main` branch
+
+    ```bash
+    git checkout main
+    ```
+3.  **Create a Branch:** Branch name should be descriptive.
+
+    ```bash
+    git checkout -b ticket-number-feature-name
+    ```
+4.  **Make your changes:**
+    *   Write clear code with comments and documentation.
+    *   Include unit tests (if applicable).
+    *   Commit frequently with descriptive messages.
+5.  **Push your branch:**
+
+    ```bash
+    git push origin ticket-number-feature-name
+    ```
+6.  **Create Pull Request:** Create a PR against the `main` branch. Include a
+      summary of changes, link to the issue (if applicable), context, and
+      testing instructions.
+7. **Request Review:** Request code review and reassign ticket.
+8. **Assign Ticket:** After code review, assign back to original ticket holder.
+9. **Merging:** Ticket holder merges their PR and changes ticket status to done.

docs/docs/development/local/index.md

@@ -11,11 +11,13 @@ to run a version of the site locally, at the following URLs:
 | *URL*                              | *Purpose*
 |------------------------------------| ------------------
 | https://performance.ddev.site      | [Drupal back end](../back-end)
-| https://performance.ddev.site:3000 | [Next.js front end](../front-end)
-| https://performance.ddev.site:3999 | Documentation
+| https://localhost:3000             | [Next.js front end](../front-end)
+| https://performance.ddev.site:4000 | Documentation
 
 ## DDEV
 
+DDEV is an open-source tool that simplifies the process of creating and managing local development environments, particularly for PHP-based projects like Drupal. It uses Docker to provide consistent, reproducible environments with pre-configured services, allowing developers to focus on coding rather than environment setup.
+
 Before setting up a local environment, refer to the
 [getting started](https://ddev.readthedocs.io/en/stable/) guide to prepare your
 computer to run this site using DDEV.
@@ -36,7 +38,45 @@ ddev start
 
 The site will now be available at the above URLs.
 
-## Site Database
+## Install Dependencies Using Composer
+
+In a Drupal project, Composer manages all the PHP dependencies, including Drupal core, contributed modules, and libraries. It automates the process of downloading, installing, and updating these components, ensuring that all required elements are present and compatible, leading to a more stable and maintainable codebase.
+
+```shell
+# Install dependencies
+ddev composer install
+```
+
+## Drupal Site Install and Config Import
+
+Drupal site install is the process of setting up a fresh Drupal instance, configuring the database, creating the initial admin user, and enabling necessary modules. It essentially lays the foundation for a functional Drupal website, allowing you to then customize it with content, themes, and configurations.
+
+Drupal configuration refers to the settings and options that define how a Drupal website functions, encompassing things like content types, user roles, views, and system settings. These configurations, which can be exported and imported, allow for consistent and reproducible site setups across different environments, making development and deployment more efficient. 
+
+If no database exists, you can import exiting config as part of the initial site install.
+
+```shell
+# Run site install and import config
+ddev drush site-install --existing-config
+```
+
+If the database already exits, then you may import the config into the existing site.
+
+```shell
+# Import config into an existing site
+ddev drush config:import
+```
+
+## Drupal Admin Access
+
+After the local site has been installed, Drush may be used to generate a one-time login link to access the Drupal administration pages. 
+
+```shell
+# Generate one-time login link
+ddev drush user:login
+```
+
+## Site Database and Migrations
 
 Throughout the MVP development process, the database is considered disposable.
 A new site can be bootstrapped from code and populated from a fresh migration:
@@ -52,3 +92,25 @@ drush site-install --existing-config
 # Migrate content from Airtable
 ddev migrate
 ```
+
+# Next.js Decoupled Frontend
+
+This project uses Next.js as the frontend to render content fetched from a Drupal backend. This approach allows developers to leverage the benefits of both systems: Drupal's content management capabilities and Next.js's frontend development experience.
+
+```shell
+# Move to the Next.Js install directory
+cd src/frontend
+
+# Install dependencies
+npm install
+
+# Create a local env file from the example file
+cp .env.example .env.local
+
+# Start the local dev server
+npm run dev
+```
+
+## Next.js for Drupal Oauth Client Config
+
+An OAuth client must be set up in Drupal before the decoupled Next.Js frontend can connect to and consume content from Drupal. Follow the instructions in the [Next.Js for Drupal documentation](https://next-drupal.org/learn/preview-mode/create-oauth-client) to configure the OAuth client locally.

docs/docs/intro.md

@@ -3,5 +3,70 @@ sidebar-position: 1
 slug: /
 title: PGOV Overview
 ---
-# Technical documentation
 
+# Performance.gov
+
+Performance.gov is a digital product from the U.S. government that helps the
+American public–especially civil society professionals–track the progress of
+U.S. strategic goals and find opportunities to contribute. Performance.gov
+fulfills the legal requirement established by the Government Performance and
+Results Modernization Act of 2010 that Federal performance information must be
+consolidated and presented on a single website, such that it provides “a
+coherent picture of . . . the performance of the federal government and
+individual agencies.
+
+## Technical overview
+
+Performance.gov is built using a decoupled architecture. [Drupal](https://drupal.org) is used
+as the back-end content management system, while [Next.js](https://nextjs.org/)
+is used for the site's front end.
+
+### Drupal
+
+Drupal is a free and open-source content management system (CMS). It's built to
+be flexible and adaptable, letting you manage content for different uses beyond
+just regular websites.
+
+Drupal's modular design means you can customize it to fit your needs, from
+simple sites to complex apps that handle lots of data. Drupal has powerful content
+management features, user management, editorial workflows, and reliable content
+architectures.
+
+This site uses uses Next.js as a separate, decoupled front end framework, which
+it can be updated and managed separately.
+
+[Learn more about the Drupal implementation](development/back-end)
+
+### Next.js
+
+Next.js is a popular open-source React framework for building fast and modern
+web applications. It's known for features like server-side rendering (SSR),
+static site generation (SSG), and built-in routing, which contribute to improved
+performance, SEO, and a better user experience. Next.js handles a lot of the
+complex setup typically required for React projects, making it easier to focus
+on building the application itself.
+
+When used as the front end for a decoupled Drupal site, Next.js becomes the
+presentation layer, responsible for fetching content from Drupal and displaying
+it to the user. Next.js can communicate with Drupal's API endpoints, including
+those provided by JSON:API or a GraphQL endpoint.
+
+Combining Next.js with a decoupled Drupal back end provides a powerful and
+flexible architecture. Drupal handles content creation, management, and storage,
+while Next.js focuses on delivering a performant and engaging user experience.
+This separation of concerns allows developers to leverage the strengths of both
+technologies, resulting in a scalable and maintainable web application.
+
+[Learn more about the Next.js Front end](development/front-end)
+
+### Next.js for Drupal
+
+This site utilizes the [Next.js for Drupal](https://next-drupal.org/) project.
+Next.js for Drupal is a powerful toolkit designed to streamline the development
+of decoupled Drupal websites using Next.js as the front end. It provides a set
+of pre-built components, functions, and utilities that simplify common tasks
+like fetching Drupal content, handling authentication, and managing routing. By
+abstracting away much of the boilerplate code typically associated with
+decoupled Drupal development, Next.js for Drupal allows developers to focus on
+building unique features and delivering exceptional user experiences. It offers
+a well-defined structure and best practices, making it easier to create performant, scalable, and maintainable decoupled Drupal applications with Next.js.