Merge pull request #120 from microbiomedata/99-document-repository-st…

…ructure-and-procedures-for-content-contributors Update repository documentation to reflect recent changes
microbiomedata · Dec 21, 2024 · 04863ce · 04863ce
2 parents 4999094 + 2161951
commit 04863ce
Show file tree

Hide file tree

Showing 2 changed files with 162 additions and 126 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,23 @@
 # Docs
 
-> [!NOTE]  
-> This repository is in early development.
-> We are currently in the process of reviewing, pruning, and consolidating our documentation.
-
 ## Introduction
 
-This repository contains the content that we compile into our
-[documentation website](https://microbiomedata.github.io/docs).
+This repository underlies the NMDC [documentation website](https://docs.microbiomedata.org).
+
+The NMDC documentation website is made up of three sections: Home, Runtime, and Workflows. The content for some of those
+sections resides in this repository, while the content for others of those sections resides in other repositories.
+The NMDC documentation website is generated by pulling in the remote content, compiling each section on its own,
+and then merging all the compiled sections into a single website.
+
+```mermaid
+flowchart TD
+    home("Home")
+    runtime("Runtime")
+    workflows("Workflows")
+
+    home --> runtime
+    home --> workflows
+```
 
 ## Table of contents
 
@@ -16,161 +26,91 @@ This repository contains the content that we compile into our
   * [Introduction](#introduction)
   * [Table of contents](#table-of-contents)
   * [Repository structure](#repository-structure)
-    * [Content](#content)
-      * [Maintenance](#maintenance)
-        * [Basic workflow (to edit 1 file)](#basic-workflow-to-edit-1-file)
-        * [Intermediate workflow (to edit 1+ files)](#intermediate-workflow-to-edit-1-files)
-    * [Code](#code)
-    * [Repository-level configuration files and documentation](#repository-level-configuration-files-and-documentation)
-      * [GitHub Actions](#github-actions)
-  * [Development](#development)
-    * [Spin up the development environment](#spin-up-the-development-environment)
-    * [Watch for changes](#watch-for-changes)
-      * [Home docs](#home-docs)
-      * [Runtime docs](#runtime-docs)
-      * [Workflow docs](#workflow-docs)
-* [TODO](#todo)
+  * [Content Editor Quick Reference ✍️](#content-editor-quick-reference-)
+  * [The Home section](#the-home-section)
+    * [Making changes](#making-changes)
+      * [Basic workflow (to edit 1 file)](#basic-workflow-to-edit-1-file-)
+      * [Intermediate workflow (to edit 1+ files)](#intermediate-workflow-to-edit-1-files)
+  * [Developer documentation](#developer-documentation)
 <!-- TOC -->
 
 ## Repository structure
 
-This repository has the following sections:
+The repository has the following top-level directories:
+
+- `.docker/` - this directory contains files only used in the Docker-based development environment
+- `.github/` - this directory contains GitHub Actions workflow specifications
+- `content/` - this directory contains the source files for the Home section of the website
+- `pullers/` - this directory contains files related to pulling and compiling remote content into the website
+
+Some of those top-level directories have their own `README.md` files, which further describe the directories' contents.
+
+## Content Editor Quick Reference ✍️
+
+Here is a table showing the locations of files you can edit in order to make changes to a given section of the website:
 
-> [!NOTE]
-> TODO
+| To edit content in this section... | Edit files in...                                                             |
+|------------------------------------|------------------------------------------------------------------------------|
+| Home                               | The `content/home` folder in this repo                                       |
+| Runtime                            | The `docs` folder in the `nmdc-runtime` repo                                 |
+| Workflows (Overview or Index)      | The `pullers/workflow_docs` folder in this repo                              |
+| Workflows (Chapter 1)              | The `pullers/workflow_docs/metagenome_workflow_overview` folder in this repo |
+| Workflows (Everything else)        | The `docs` folder of the respective workflow repo                            |
 
-### Content
+The website will automatically be regenerated and redeployed whenever a new commit is made on—or merged into—the
+`main` branch of the repository. The regeneration and redeployment process usually takes about three to complete.
 
-The `./content/home` directory contains the portion of our documentation that is not pulled from an external repository.
-This directory began as an almost 1-to-1 copy of the `NMDC_documentation` repository. More details about what was and
-wasn't copied is available [here](./content/home/README.md).
+## The Home section
 
-#### Maintenance
+The `content/home/` directory contains the source files for the Home section of the website.
+This directory began as an almost 1-to-1 copy of the `NMDC_documentation` repository. More details about what was—and
+wasn't—copied is available [here](./content/home/README.md).
+This section of the website is generated using [Sphinx](https://www.sphinx-doc.org), a static site generator.
+Its content is organized according to the [Diátaxis](https://diataxis.fr/how-to-use-diataxis/#use-diataxis-as-a-guide-not-a-plan) guidelines.
 
-This documentation is implemented within the [Sphinx](https://www.sphinx-doc.org) framework.
-The content is organized according to the
-[Diátaxis](https://diataxis.fr/how-to-use-diataxis/#use-diataxis-as-a-guide-not-a-plan) guidelines.
+### Making changes
 
-Here's how you can make (technically, "propose") changes to this documentation:
+Here's how you can make (technically, "propose") a change to this section of the website:
 
 > **Note:** The high-level process may be familiar to you: (1) create a GitHub Issue, (2) create a branch associated
 > with that Issue, (3) make changes on that branch, and (4) create a Pull Request to merge that branch into `main`.
-> You can use whatever workflow you want in order to follow that process. The following are some example workflows:
+> You can use whatever workflow you want in order to do those things. The following are some example workflows we've
+> documented for our teammates.
 
-##### Basic workflow (to edit 1 file)
+#### Basic workflow (to edit 1 file) 
 
-1. Create a GitHub Issue describing what you want to change (e.g. "Fix Foo in Bar")
-2. On GitHub, go to the file within `./content/home/src` that you want to edit
+1. Create a GitHub Issue describing the issue you want to address (e.g. "`Link is broken`")
+2. On GitHub, go to the file within `content/home/src` that you want to edit
 3. Click the "Edit this file" button (i.e. the pencil icon button) at the upper right
-4. Edit the file
+4. Edit the file, making the changes you want to make
 5. Click the "Commit changes..." button at the upper right
 6. Customize the commit message to tell others what you did (e.g. "`Fix typo in link`")
 7. Mark the bubble that says "**Create a new branch** for this commit and start a pull request"
-8. (Recommended) Customize the branch name so it starts with the GitHub Issue number (e.g. `123-fix-foo-in-bar`)
+8. (Recommended) Customize the branch name so it starts with the GitHub Issue number (e.g. `123-link-is-broken`)
 9. Click "Propose changes"
 10. Fill in the Pull Request form and click "Create pull request"
 
 You will end up with a Pull Request (PR) containing the changes. Once the PR gets merged into `main`,
-the documentation website will automatically be updated to reflect the changes.
+the documentation website will automatically be updated to reflect the changes you made.
 
-##### Intermediate workflow (to edit 1+ files)
+#### Intermediate workflow (to edit 1+ files)
 
-1. Create a GitHub Issue describing what you want to change (e.g. "Fix Foo in Bar")
+1. Create a GitHub Issue describing the issue you want to address (e.g. "`Link is broken`")
 2. Visit https://github.dev/microbiomedata/docs/
 3. Click the branch name (e.g. `main`) at the lower left
 4. Click "Create a new branch..." at the top
-5. Enter a name for the branch, beginning with an issue number (e.g. `123-fix-foo-in-bar`)
+5. Enter a name for the branch, beginning with an issue number (e.g. `123-link-is-broken`)
 6. (If prompted) Click "Switch to Branch"
-7. Make changes in `./content/home/src`
+7. Make changes in `content/home/src`
 8. Click the "Source Control" icon in the left sidebar (3rd from the top)
 9. Hover over the "Changes" heading and click the `+` icon that appears
 10. Enter a commit message to tell others what you did (e.g. "`Fix typo in link`")
 11. Click the "Commit & Push" button
 12. Visit https://github.com/microbiomedata/docs/ and create a Pull Request for that branch
 
 You will end up with a Pull Request (PR) containing the changes. Once the PR gets merged into `main`,
-the documentation website will automatically be updated to reflect the changes.
-
-### Code
-
-> [!NOTE]  
-> TODO
-
-### Repository-level configuration files and documentation
-
-- `.github/workflows`: GitHub Actions workflows
-- `docker-compose.yml`: Specification for a _set_ of container images you can use when editing _any_ section of our documentation website
-- `README.md`: This document
-
-#### GitHub Actions
-
-The `.github/workflows` directory contains YAML files that we use to configure GitHub Actions.
-We use GitHub Actions to (a) compile local and remote content into a website,
-and to (b) publish that website to the Internet.
-
-## Development
-
-### Spin up the development environment
-
-Assuming you have Docker installed, you can spin up the development environment by running: 
-
-```shell
-docker compose up --detach
-```
-
-That will start up several Docker containers, which you can access via the URLs below:
-
-- http://localhost:5000 - the entire website
-- http://localhost:5002 - only the home docs portion of the website
-- http://localhost:5003 - only the Runtime docs portion of the website
-- http://localhost:5004 - only the workflow docs portion of the website
-
-### Watch for changes
-
-#### Home docs
-
-Whenever you update files in the `content/home/src` directory,
-the home docs portion of the website will be automatically rebuilt.
-Refresh your web browser to see that newly-rebuilt portion of the website.
-
-#### Runtime docs
-
-Nothing will automatically happen in the development environment when someone
-updates files in the **upstream** Runtime repository. To adopt those changes
-in the development environment, rebuild the `runtime-docs` container
-by issuing the following sequence of commands:
-
-```shell
-docker compose down             runtime-docs
-docker compose build --no-cache runtime-docs
-docker compose up --detach      runtime-docs
-```
-
-#### Workflow docs
-
-Nothing will automatically happen in the development environment when someone
-updates files in the **upstream** workflow repositories. To adopt those changes
-in the development environment, rebuild the `workflow-docs` container
-by issuing the following sequence of commands:
-
-```shell
-docker compose down             workflow-docs
-docker compose build --no-cache workflow-docs
-docker compose up --detach      workflow-docs
-```
-
-If you **only** make changes to the documentation source files that reside in _this_ repository
-(i.e. those in `pullers/workflow_docs`), then you can issue this sequence of commands instead,
-which will allow Docker to _avoid refetching_ the source files from the upstream repos:
-
-```shell
-docker compose down             workflow-docs
-docker compose build            workflow-docs
-docker compose up --detach      workflow-docs
-```
+the documentation website will automatically be updated to reflect the changes you made.
 
-# TODO
+## Developer documentation
 
-- [ ] Populate the "TODO" sections above
-- [ ] Add package version constraints to `content/home/requirements.txt`
-- [ ] Document Google Analytics usage
+Developer documentation is in [development.md](./development.md).
diff --git a/development.md b/development.md
@@ -0,0 +1,96 @@
+# Development
+
+## Introduction
+
+This document contains information about the infrastructure aspect of the documentation website,
+as opposed to the content aspect.
+
+## Table of contents
+
+<!-- TOC -->
+* [Development](#development)
+  * [Introduction](#introduction)
+  * [Table of contents](#table-of-contents)
+  * [Local development](#local-development)
+    * [Spin up the development environment](#spin-up-the-development-environment)
+    * [Applying changes](#applying-changes)
+      * [Home section](#home-section)
+      * [Runtime section](#runtime-section)
+      * [Workflow docs](#workflow-docs)
+  * [Deployment](#deployment)
+  * [Google Analytics](#google-analytics)
+<!-- TOC -->
+
+## Local development
+
+This section is about running an instance of the website locally.
+
+### Spin up the development environment
+
+Assuming you have Docker installed, you can spin up the development environment by running: 
+
+```shell
+docker compose up --detach
+```
+
+That will start up several Docker containers, which you can access via the URLs below:
+
+- http://localhost:5000 - the entire website
+- http://localhost:5002 - only the Home section of the website
+- http://localhost:5003 - only the Runtime section of the website
+- http://localhost:5004 - only the Workflows section of the website
+
+### Applying changes
+
+#### Home section
+
+Whenever you update files in the `content/home/src` directory,
+the Home section of the website will be automatically rebuilt.
+Refresh your web browser to see that newly-rebuilt section of the website.
+
+#### Runtime section
+
+Nothing will automatically happen in the development environment when someone
+updates files in the **upstream** Runtime repository. To adopt those changes
+in the development environment, rebuild the `runtime-docs` container
+by issuing the following sequence of commands:
+
+```shell
+docker compose down             runtime-docs
+docker compose build --no-cache runtime-docs
+docker compose up --detach      runtime-docs
+```
+
+#### Workflow docs
+
+Nothing will automatically happen in the development environment when someone
+updates files in the **upstream** workflow repositories. To adopt those changes
+in the development environment, rebuild the `workflow-docs` container
+by issuing the following sequence of commands:
+
+```shell
+docker compose down             workflow-docs
+docker compose build --no-cache workflow-docs
+docker compose up --detach      workflow-docs
+```
+
+If you **only** make changes to the documentation source files that reside in _this_ repository
+(i.e. those in `pullers/workflow_docs`), then you can issue this sequence of commands instead,
+which will allow Docker to _avoid refetching_ the source files from the upstream repos:
+
+```shell
+docker compose down             workflow-docs
+docker compose build            workflow-docs
+docker compose up --detach      workflow-docs
+```
+
+## Deployment
+
+The `.github/workflows` directory contains YAML files that we use to configure GitHub Actions.
+We use GitHub Actions to (a) compile local and remote content into a single website,
+and to (b) publish that single website to GitHub Pages.
+
+## Google Analytics
+
+We use Google Analytics to collect and analyze website traffic. You can search the repository for
+our Google Analytics Property ID (i.e. "`G-VH6HKVLCWN`") in order to learn more.