docs: project readme polish (#174)

README.md

@@ -9,7 +9,7 @@ Extensions of the [Core CMS] project
 - [Start Project](#start-project)
 - [Update Project](#update-project)
 - [Run Project](#run-project)
-- [Develop Project](#develop-project)
+- [Develop Project](./docs/develop-project.md)
 - [Build Project](#build-project)
 - [Deploy Project](https://confluence.tacc.utexas.edu/x/Lo99E) (at "Core-CMS-Custom" section)
 - [Port Project](./docs/port-project.md)
@@ -131,10 +131,10 @@ To run multiple projects, first read [Multiple Projects](./docs/run-project.md#m
 
 ## Develop Project
 
-### Running a Custom App
+To develop a new project, read [Develop Project](./docs/develop-project.md) e.g.
 
-- Update `custom_app_settings.py` with relevant content from [TACC/Core-CMS:`/taccsite_cms/custom_app_settings.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/custom_app_settings.example.py).
-- Update `urls_custom.py` with relevant content from [TACC/Core-CMS:`/taccsite_cms/urls_custom.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/urls_custom.example.py).
+- [Customize Project](./docs/develop-project.md#customize-project)
+- [Create a Custom App](./docs/develop-project.md#create-a-custom-app)
 
 ## Build Project
 

apcd-cms/README.md

@@ -1,7 +1,9 @@
-# apcd-cms
+# APCD
+
+https://democratizingdata.ai/
 
 An extension of the [Core CMS](https://github.com/TACC/Core-CMS) project
 
-## Basic Set Up
+## Basics
 
-See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom).
+See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom#readme).

demdata_cms/README.md

@@ -1,7 +1,9 @@
-# apcd-cms
+# Democratizing Data
+
+https://democratizingdata.ai/
 
 An extension of the [Core CMS](https://github.com/TACC/Core-CMS) project
 
-## Basic Set Up
+## Basics
 
-See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom).
+See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom#readme).

docs/develop-project.md

@@ -0,0 +1,61 @@
+# Develop Project
+
+## Table of Contents
+
+- [Remove Excess Content](#remove-excess-content)
+- [Customize Project](#customize-project)
+- [Create a Custom App](#create-a-custom-app)
+- [Change All Projects](#change-all-projects)
+
+## Create a New Project
+
+1. Clone [example_cms](../example_cms).
+2. Name the directory as WMA Infrastructure team defines e.g. `demdata_cms`.
+3. [Remove Excess Content](#remove-excess-content)
+4. [Customize Project](#customize-project)
+5. Perform instructions in other pertinent sections.
+
+## Remove Excess Content
+
+> **Note**
+> [Core CMS] supports standard TACC apps, URLs, and static asset directories. Consider its capabilities before creating something new.
+
+| <u>If</u> Project Does Not Need | <u>Then</u> Delete |
+| - | - |
+| additional apps | `apps/` |
+| URLs for custom apps | `urls_custom.py` |
+| custom code | `custom_app_settings.py` |
+
+## Customize Project
+
+Edit `settings_custom.py`. To know what settings are available, see [Core-CMS `settings.py`](https://github.com/TACC/Core-CMS/blob/main/taccsite_cms/settings.py).
+
+The settings usually edited are `LOGO` and `..._BRANDING`.
+
+## Create a Custom App
+
+- Update `custom_app_settings.py` with pertinent content from [TACC/Core-CMS:`/taccsite_cms/custom_app_settings.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/custom_app_settings.example.py).
+- Update `urls_custom.py` with pertinent content from [TACC/Core-CMS:`/taccsite_cms/urls_custom.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/urls_custom.example.py).
+
+## Change All Projects
+
+If there is a change that should be made in all CMS projects, consider whether it can be done in a more appropriate repository.
+
+| Type of Change | Repository |
+| - | - |
+| CMS feature / default setting | [Core CMS] |
+| styles specific to CMS[^1] | [Core CMS] |
+| [TACC UI Patterns] [^2] | [Core Styles] |
+| [Core Portal] |
+
+[^1]: These are not always obviously distinct from [Core Styles]. Examples may be the News plugin, the Image Gallery, forms, and any "Core CMS" patterns in [TACC UI Patterns].
+
+[^2]: There may be styles from [Core Styles] that are not documented in [TACC UI Patterns].
+
+<!-- Link Aliases -->
+
+[Core CMS]: https://github.com/TACC/Core-CMS
+[Core Portal]: https://github.com/TACC/Core-Portal
+[Core Styles]: https://github.com/TACC/Core-Styles
+
+[TACC UI Patterns]: https://tacc.utexas.edu/static/ui/

docs/run-project.md

@@ -48,4 +48,6 @@ To run multiple projects simultaneously:
 
 [^2]: Advanced adaptation of these instructions may support retaining database access, et cetera.
 
+<!-- Link Aliases -->
+
 [copy a database]: https://confluence.tacc.utexas.edu/pages/viewpage.action?pageId=249135195

example_cms/README.md

@@ -1,7 +1,7 @@
-# matcssi_cms
+# Example
 
 An extension of the [Core CMS](https://github.com/TACC/Core-CMS) project
 
-## Basic Set Up
+## Basics
 
-See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom).
+See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom#readme).

matcssi_cms/README.md

@@ -1,7 +1,9 @@
-# matcssi_cms
+# MatCSSI
+
+https://matcssi.tacc.utexas.edu/
 
 An extension of the [Core CMS](https://github.com/TACC/Core-CMS) project
 
-## Basic Set Up
+## Basics
 
-See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom).
+See [Core-CMS-Custom](https://github.com/TACC/Core-CMS-Custom#readme).