Add documentation organization system

For:
#14

README.md

@@ -1,34 +1,5 @@
 # affils
 
-affils is ClinGen's affiliations service. It is under development. See
-our [roadmap](https://github.com/ClinGen/affils/issues/1).
-
-## Getting started
-
-The affils project uses [Pipenv](https://pipenv.pypa.io/en/latest/index.html)
-to manage its dependencies. (Do not use the `requirements.txt` file.
-The `requirements.txt` file is generated and used in GitHub Actions.)
-For all other command line tasks, the affils project uses [Invoke](https://docs.pyinvoke.org/en/stable/index.html).
-
-1. Install Python 3.12+.
-2. Install [Pipenv](https://pipenv.pypa.io/en/latest/index.html): `pip install --user pipenv`.
-3. Activate a virtual environment: `pipenv shell`.
-4. Install dependencies: `pipenv sync --dev`.
-5. Run the development server: `invoke dev` or `inv dev`.
-6. Read the `tasks.py` module for other command line tasks.
-7. Read the [standards document](./doc/standards.md).
-
-## Affiliations workflow
-
-We have diagrams for our current and desired affiliations workflow in
-the [diagrams directory](./doc/diagrams).
-
-## Environment variables
-
-We use environment variables files (commonly referred to as `.env`
-files) to configure the affiliations service. For more info on how we
-use `.env` files, see the [doc on environment variables](./doc/envars.md).
-
-## Deployment
-
-Read the [doc on deploying to production](./doc/deploy.md).
+affils is Stanford ClinGen's affiliations service. It is under
+development. See our [roadmap](https://github.com/ClinGen/affils/issues/1)
+and our [documentation](./doc/README.md).

doc/README.md

@@ -0,0 +1,39 @@
+# Documentation
+
+This is the documentation for the affiliations service. We follow the
+[Divio documentation organization system](https://documentation.divio.com/introduction.html).
+
+- [Tutorials](./tutorial.md) (learning-oriented)
+    - Tutorials are lessons that take the reader by the hand through a series of
+      steps to complete a project of some kind. Unlike how-to guides, tutorials
+      don't assume lots of prerequisite knowledge.
+    - [Get started](./tutorial.md#get-started)
+- [How-to guides](./howto.md) (problem-oriented)
+    - How-to guides take the reader through the steps required to solve a
+      real-world problem. They are recipes, directions to achieve a specific
+      end. Unlike tutorials, they typically assume a fair amount of prerequisite
+      knowledge.
+    - [Run code checks](./howto.md#run-code-checks)
+    - [Organize imports and constants](./howto.md#organize-imports-and-constants)
+    - [Write a TODO comment](./howto.md#write-a-todo-comment)
+    - [Write a commit message](./howto.md#write-a-commit-message)
+    - [Set up Postgres locally](./howto.md#set-up-postgres-locally)
+    - [View info on AWS](./howto.md#view-info-on-aws)
+    - [View logs on AWS](./howto.md#view-logs-on-aws)
+    - [Deploy to AWS](./howto.md#deploy-to-aws)
+- [Explanations](./explanation.md) (understanding-oriented)
+    - Explanation, or discussions, clarify and illuminate a particular topic.
+      They broaden the documentation’s coverage of a topic. Explanations can
+      equally well be described as discussions; they are discursive in nature.
+      They are a chance for the documentation to relax and step back from the
+      software, taking a wider view, illuminating it from a higher level or even
+      from different perspectives. You might imagine a discussion document being
+      read at leisure, rather than over the code.
+    - [Affiliations workflow diagrams](./explanation.md#affiliations-workflow-diagrams)
+    - [Environment variables](./explanation.md#environment-variables)
+- [Reference guides](./reference.md) (information-oriented)
+    - Reference guides are technical descriptions of the machinery and how to
+      operate it. Reference guides have one job only: to describe. They are
+      code-determined, because ultimately that’s what they describe: key
+      classes, functions, APIs, and so they should list things like functions,
+      fields, attributes and methods, and set out how to use them.

doc/envars.md → doc/explanation.md

@@ -1,4 +1,11 @@
-# Environment variables
+# Explanations
+
+## Affiliations workflow diagrams
+
+We have diagrams for our current and desired affiliations workflow in
+the [diagrams directory](./diagrams).
+
+## Environment variables
 
 There's a `.env.template` file that is the source of truth for
 environment variable keys. You're supposed to create a `.env.local` file

doc/howto.md

@@ -0,0 +1,137 @@
+# How-to guides
+
+## Run code checks
+
+Code should be:
+
+1. automatically formatted using [Black](https://github.com/psf/black),
+2. linted using [Pylint](https://github.com/pylint-dev/pylint),
+3. type-checked using [mypy](https://mypy-lang.org/), and
+4. tested using [Pytest](https://github.com/pytest-dev/pytest/).
+
+To run these checks:
+
+```
+inv check
+```
+
+## Organize imports and constants
+
+At the top of any given module there will probably be imports and
+constants. Our preferred way of organizing them is as follows:
+
+```
+# Built-in libraries:
+# [Built-in libraries go here.]
+
+# Third-party dependencies:
+# [Third-party dependencies installed via Pipenv go here.]
+
+# In-house code:
+# [In-house code imports go here.]
+
+# Constants:
+FOO = "foo"
+BAR = 123
+```
+
+Each of the sections should be sorted alphabetically.
+
+## Write a TODO comment
+
+TODO comments should include the name of the person who wrote the TODO
+comment and a link to a GitHub issue describing the TODO in more depth.
+
+## Write a commit message
+
+When writing a commit, follow the example provided here:
+
+```
+Describe how to write a good commit
+
+The first line of a commit message serves as a summary. When displayed
+on the web, it's often styled as a heading, and in emails, it's
+typically used as the subject. As such, you should capitalize it and
+omit any trailing punctuation. Aim for about 50 characters, give or
+take, otherwise it may be painfully truncated in some contexts. Write
+it, along with the rest of your message, in the imperative tense: "Fix
+bug" and not "Fixed bug" or "Fixes bug". Consistent wording makes it
+easier to mentally process a list of commits.
+
+Oftentimes a subject by itself is sufficient. When it's not, add a blank
+line (this is important) followed by one or more paragraphs hard wrapped
+to 72 characters. Git is strongly opinionated that the author is
+responsible for line breaks; if you omit them, command line tooling will
+show it as one extremely long unwrapped line. Fortunately, most text
+editors are capable of automating this.
+
+A commit should almost always be linked to a GitHub issue.
+
+For:
+https://github.com/org/repo/issues/123
+```
+
+## Set up Postgres locally
+
+This how-to guide assumes you are using macOS. The steps will be
+different for different operating systems.
+
+- Install Postgres: `brew install postgresql@16`
+- Start Postgres now and restart at login: `brew services start postgresql@16`
+- Add Postgres to your PATH: `export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"`
+    - If you are using Zsh (the default shell on macOS), I believe this
+      can go in `.zshrc` in your home directory.
+    - If you use a different shell, the file you put this in might be
+      different, and the syntax might be different.
+- Either reload your shell configuration or restart your terminal
+  session so Postgres executables will be on your PATH.
+- Run `which psql`. You should see: `/opt/homebrew/opt/postgresql@16/bin/psql`
+- Enter the Postgres shell as the default user: `psql postgres`
+- Create the affiliations database: `CREATE DATABASE affils;`
+- Create a new user for the affiliations service:
+```
+CREATE USER affils WITH PASSWORD 'password';
+GRANT ALL PRIVILEGES ON DATABASE affils TO affils;
+```
+- Change the owner of the database:
+```
+ALTER DATABASE affils OWNER TO affils;
+```
+- Create and fill out a `.env.local` file in the root of the
+  affiliations repository.
+    - The values you should fill in should be in the `.env.template`
+      file.
+    - See [the doc on environment variables](./envars.md) for more info
+      on environment variables.
+    - The default Postgres port is 5432.
+    - For local development, the host should be localhost.
+
+## View info on AWS
+
+The affils service is deployed to AWS's Elastic Beanstalk service. If
+you use your Stanford credentials to log in to AWS, choose the
+production profile, and set your region to Oregon (us-west-2), and then
+you navigate to the Elastic Beanstalk console, you should see an Elastic
+Beanstalk environment called `affils-env`. The `affils-env` environment
+contains the `affils` application. If you click the `affils`
+application, you should be able to view information about the affils
+service.
+
+## View logs on AWS
+
+When running locally, logs are written to stdout. When running on AWS,
+logs can be viewed in CloudWatch. To view the logs, navigate to the
+CloudWatch web console, then in the side bar click the link to the log
+groups page. Then look for the `web.stdout.log` log group. Then click
+the appropriate log stream (probably the most recent one).
+
+## Deploy to AWS
+
+To deploy the files from your computer, enter the following:
+
+```
+inv deploy
+```
+
+This command should upload the affils files from your computer to AWS's
+Elastic Beanstalk service.

doc/reference.md

@@ -0,0 +1 @@
+# Reference guides

doc/tutorial.md

@@ -0,0 +1,10 @@
+# Tutorials
+
+## Get started
+
+1. Install Python 3.12+.
+2. Install [Pipenv](https://pipenv.pypa.io/en/latest/index.html): `pip install --user pipenv`.
+3. Activate a virtual environment: `pipenv shell`.
+4. Install dependencies: `pipenv sync --dev`.
+5. [Set up Postgres locally](./howto.md#set-up-postgres-locally)
+6. Run the development server: `invoke dev` or `inv dev`.