Merge pull request #596 from hackforla/hackforla/develop

update mkdocs

mkdocs/docs/developer/backend.md

@@ -44,6 +44,8 @@ _<p style="text-align: center;">Overall project structure</p>_
 
 _<p style="text-align: center;">Backend Architecture</p>_
 
+These diagrams show how data flows through the app: [Frontend and Backend UML diagrams](https://github.com/hackforla/CivicTechJobs/issues/236)
+
 ## Summary
 
 **Backend Tech Stack**: Django, DjangoRESTFramework

mkdocs/docs/developer/frontend.md

@@ -57,6 +57,8 @@ _<p style="text-align: center;">Overall project structure</p>_
 
 _<p style="text-align: center;">Frontend Architecture</p>_
 
+These diagrams show how data flows through the app: [Frontend and Backend UML diagrams](https://github.com/hackforla/CivicTechJobs/issues/236)
+
 ## Summary
 
 **Frontend Tech Stack**: React, Babel, webpack, Jest, React Testing Library, HTML, SCSS, JS, TailwindCSS

mkdocs/docs/developer/mkdocs-architecture.md

@@ -101,6 +101,8 @@ The docs are set to automatically deploy to github pages using the `mkdocs-build
 
 ### Github Action for mkdocs deployment
 
+Links to the github action: [Build MkDocs site (develop)](https://github.com/hackforla/CivicTechJobs/actions/workflows/mkdocs-build.yml)
+
 ```yml
 name: Build MkDocs site (develop)
 

mkdocs/docs/developer/mkdocs-edit-instructions.md

@@ -1,9 +1,21 @@
-# How to Edit MkDocs
+# How to Publish new Documentation
 
-To make changes to the docs, you have to edit the `.md` files located in the `mkdocs/docs/` folder. To make a new page, you have to create a new `.md` file in the appropriate folder.
+The goal of this page is to document how to create and publish new changes to the CTJ documentation.
+
+Writing documentation into mkdocs requires some knowledge of [Markdown](https://www.markdownguide.org/).
+
+### Making changes to the mkdocs
+
+What you essentially need to know:
+
+- To make changes to the docs, edit the `.md` files located in the `mkdocs/docs/` folder.
+- To make a new page, create a new `.md` file in the appropriate folder.
+- To add or edit links in the navmenu, configure the `mkdocs.yml` file.
 
 MkDocs provides a development server that makes it convenient to see your changes in `localhost` before you deploy them to github.
 
+*For more a detailed editing guide please see the official [MkDocs Tutorial](https://www.mkdocs.org/getting-started/)*
+
 ### Quickstart
 
 To start the development server, simply go to the root of your project in the terminal and run the following command:
@@ -28,6 +40,8 @@ If anything goes wrong, you can investigate the workflow in the project's [githu
 
 **Note**: At the moment, the docs are set to deploy from the `develop` branch, using the github action located in `mkdocs-build.yml`. This means that whenever a file is changed inside the `mkdocs/` directory, and is merged into the `develop` branch on github, the changes will be automatically deployed to the official site hosted on github pages. In the near future we will set it to deploy from the `main` branch.
 
+*Check out our [MkDocs Architecture](mkdocs-architecture.md) page for more details on how it all fits together.*
+
 ### Recap
 
 To sum it all up, you can make changes in 4 easy steps:

mkdocs/docs/developer/mkdocs.md → mkdocs/docs/developer/mkdocs-guide.md

@@ -1,13 +1,15 @@
-# MkDocs guide
+# MkDocs - Documentation Guide
 
 We are using mkdocs to handle documentation.
 
-Developers should document their architectural and coding decisions in here, so that other team members can easily reference these docs whenever they are lost or confused or new to the project.
+Developers should document their architectural and coding decisions, so that other team members can easily reference these docs whenever they are lost or confused or new to the project.
 
 ### What is MKdocs?
 
 [MkDocs](https://www.mkdocs.org/) is a static site generator that is designed specifically for building project documentation. It allows you to write documentation using [Markdown](https://www.markdownguide.org/), a lightweight markup language that's easy to use, and generates a clean, professional website that can be hosted on our project's GitHub Pages.
 
+Please see [MkDocs - How to Edit](mkdocs-edit-instructions.md) for instructions on how to make changes to the CTJ documentation and publish new docs.
+
 ### What should developers document?
 
 Code functionality
@@ -42,4 +44,7 @@ API Documentation
 
 ### What are best practices for documentation?
 
-Keep it updated and consistent. Be clear and concise. Write in simple terms. Use examples.
+- Keep it updated and consistent.
+- Be clear and concise.
+- Write in simple terms.
+- Use examples.

mkdocs/docs/resources.md

@@ -19,6 +19,7 @@ More resources to be added as project progresses:
 2. [Project one sheet](https://docs.google.com/document/d/1bfxY8YlyCjzCL3oP0rpa77uEY4vuymDYZY_xWEgXiGs)
 3. [Our Shared Google Drive](https://drive.google.com/drive/folders/1hXxvpC8W5Uuzjqo4CxnjDpAMI7sbVnq8?usp=sharing&pli=1)
 4. [GitHub Workflow](https://docs.google.com/document/d/1CuRX6hhWzs8ydVCnl6OrGZ4LeVSk9X_pIzoKchAqFcU)
+5. [Milestones](https://github.com/hackforla/CivicTechJobs/milestones)
 
 ### Roadmaps
 
@@ -41,6 +42,10 @@ More resources to be added as project progresses:
 4. [Task and User Flow](https://whimsical.com/ctj-task-and-user-flow-8GgB5Moy14fnQDv24o1fGC)
 5. [HfLA Website Figma - Section for Volunteer Opportunities](https://www.figma.com/design/0RRPy1Ph7HafI3qOITg0Mr/Hack-for-LA-Website?node-id=5326-26395&t=x2ib7NJm3z5aB5H0-0)
 
+### Diagrams
+
+1. [Frontend and Backend UML diagrams](https://github.com/hackforla/CivicTechJobs/issues/236)
+
 ### For Developers
 
 1. [Contributing.md](https://github.com/hackforla/CivicTechJobs/blob/main/CONTRIBUTING.md)<br>

mkdocs/mkdocs.yml

@@ -30,7 +30,7 @@ nav:
           - GitHub Architecture: developer/github.md
           - Installation Instructions: developer/installation.md
           - MkDocs Architecture: developer/mkdocs-architecture.md
-          - MkDocs Guide: developer/mkdocs.md
+          - MkDocs - Documentation Guide: developer/mkdocs-guide.md
           - MkDocs - How to Edit: developer/mkdocs-edit-instructions.md
       - Misc:
           - ADA Guide: misc/ada-guide.md