restructure the tech/program docs

Author: Niko Matsakis

src/SUMMARY.md

@@ -34,14 +34,19 @@
 # 🔧 Running the goals program
 
 * [The goals team](./admin/team.md)
-* [Team coordination](./admin/coordination.md)
 * [Running the program](./admin/running-the-program.md)
-    * [Sample: Call for Proposal blog post](./admin/samples/cfp.md)
-    * [Sample: Text for the main README](./admin/samples/main-readme.md)
-    * [Sample: Starting RFC text](./admin/samples/rfc.md)    
-    * [Sample: Goals page](./admin/samples/goals.md)    
-* [Overall setup](./admin/setup.md)
-* [Mdbook plugin details](./admin/mdbook_plugin.md)
-* [Commands you can run](./admin/commands.md)
-    * [`issues`, creating tracking issues](./admin/issues.md)
-    * [`updates`, create monthly blog post summary](./admin/updates.md) 
+    * [Team coordination](./admin/coordination.md)
+    * [Call for proposals](./admin/cfp.md)
+    * [Preparing the RFC](./admin/prepare_rfc.md)
+    * [Authoring monthly updates](./admin/author_updates.md)
+    * [Sample texts](./admin/samples.md)
+        * [Sample: Call for Proposal blog post](./admin/samples/cfp.md)
+        * [Sample: Text for the main README](./admin/samples/main-readme.md)
+        * [Sample: Starting RFC text](./admin/samples/rfc.md)    
+        * [Sample: Goals page](./admin/samples/goals.md)    
+* [Technical reference](./admin/reference.md)
+    * [Overall setup](./admin/setup.md)
+    * [Mdbook plugin details](./admin/mdbook_plugin.md)
+    * [`cargo rpg` command reference](./admin/commands.md)
+        * [`issues`, creating tracking issues](./admin/issues.md)
+        * [`updates`, create monthly blog post summary](./admin/updates.md) 

src/admin/author_updates.md

@@ -0,0 +1,27 @@
+# Author updates
+
+## Soliciting updates
+
+Triagebot can ping project-goal owners for updates. To use it, go to Zulip and execute a command like this.
+
+```
+@triagebot ping-goals 14 Oct-21
+```
+
+The first number (14) is a threshold, it is typically set to the current day of the month (e.g., the above command assumes it is Oct 14). It means "if they have posted a comment in the last 14 days, don't bug them". 
+
+The second string ("Oct-21") is the deadline for updates to be included.
+
+We need to improve this UI.
+
+## Drafting the post
+
+The `cargo rpg` tool offers the `updates` command ([documented here](./updates.md)) which will prepare a rough draft blog post using the [updates template][]. The rough draft is prepared using an LLM which will require setting up an AWS account.
+
+```bash
+> cargo rpg updates
+```
+
+Once the draft is prepared, create a hackmd in the rust-project-goals hackmd team, post it to `#project-goals` and apply edits (particularly for the flagship goals). Then open a PR against [the blog.rust-lang.org repository](https://github.com/rust-lang/blog.rust-lang.org).
+
+[updates template]: https://github.com/rust-lang/rust-project-goals/blob/main/templates/updates.hbs

src/admin/cfp.md

@@ -0,0 +1,37 @@
+# Call for proposals
+
+Each goal milestone corresponds to six months, designated in the format YYYYHN, e.g., 2024H2 or 2025H1. To launch a new goal season, you should get started a month or two before the new season starts:
+
+* For an H1 season, start around mid Oct or November of the year before.
+* For an H2 season, start around mid April or May of the year before.
+
+This is the checklist of steps to starting accepting goal proposals:
+
+* [ ] Prepare a Call For Proposals blog post on the [Inside Rust] blog based on [this sample](./samples/cfp.md).
+    * We use Inside Rust and not the Main blog because the target audience is would-be Rust contributors and maintainers.
+* [ ] Update the [main README page](../README.md) to indicate that the next round of goals is begin accepted.
+    * [Sample text to include.](./samples/main-readme.md)
+* [ ] Create a new directory `src/YYYYhN`, e.g., `src/2025h1`, with the following files. Note that the sample files below include `<!-- XXX -->` directives that are detected by the [mdbook plugin](./mdbook_plugin.md) and replaced with appropriate content automatically.
+    * A `src/YYYYhN/README.md` file that contains the draft RFC.
+        * [You can start with this sample file.](./samples/rfc.md)
+    * A `src/YYYYhN/goals.md` file containing the draft goal listing.
+        * [You can start with this sample file.](./samples/goals.md)
+    * A `src/YYYYhN/not_accepted.md` file containing the list of goals that were not accepted.
+        * [You can start with this sample file.](./samples/not_accepted.md)
+* [ ] Modify SUMMARY.md to include your new milestone with some text like what is shown below.
+
+Sample `SUMMARY.md` comments from 2025H1:
+
+```
+# ⏳ 2025H1 goal process
+
+- [Overview](./2025h1/README.md)
+- [Proposed goals](./2025h1/goals.md)
+- [Goals not accepted](./2025h1/not_accepted.md)
+```
+
+[Inside Rust]: https://blog.rust-lang.org/inside-rust/
+
+## Receiving PRs
+
+*to be written*

src/admin/commands.md

@@ -1,3 +1,3 @@
 # Commands
 
-There is a CLI for manipulating and checking project goals. You can run it with `cargo rpg` and it has a number of useful commands, described in this section. Use `cargo rpg --help` to get a summary.
+The `cargo rpg` command is a CLI for manipulating and checking project goals. This section provides a reference describing (some of) the ability commands. You can also try `cargo rpg --help` to get a summary.

src/admin/prepare_rfc.md

@@ -0,0 +1 @@
+# foo

src/admin/reference.md

@@ -0,0 +1,2 @@
+# Technical reference
+

src/admin/running-the-program.md

@@ -1,69 +1,35 @@
 # Running the program
 
 So... somebody suckered you into serving as the owner of the goals program. Congratulations!
-This page will walk you through the process.
+This page will walk you through what is involved at each step of the the process.
 
-## Call for proposals
+## Calendar
 
-Each goal milestone corresponds to six months, designated in the format YYYYHN, e.g., 2024H2 or 2025H1.
-To launch a new goal season, you should get started a month or two before the new season starts:
+This section summarizes the dates involved with a theoretical program taking place in the year 2222.
+Each item has a link to more instructions.
 
-* For an H1 season, start around mid Oct or November of the year before.
-* For an H2 season, start around mid April or May of the year before.
+Each of the calendars has someoverlap with the previous and next previous.
 
-This is the checklist of steps to starting accepting goal proposals:
+### H1 calendar
 
-* [ ] Prepare a Call For Proposals blog post on the [Inside Rust] blog based on [this sample](./samples/cfp.md).
-    * We use Inside Rust and not the Main blog because the target audience is would-be Rust contributors and maintainers.
-* [ ] Update the [main README page](../README.md) to indicate that the next round of goals is begin accepted.
-    * [Sample text to include.](./samples/main-readme.md)
-* [ ] Create a new directory `src/YYYYhN`, e.g., `src/2025h1`, with the following files. Note that the sample files below include `<!-- XXX -->` directives that are detected by the [mdbook plugin](./mdbook_plugin.md) and replaced with appropriate content automatically.
-    * A `src/YYYYhN/README.md` file that contains the draft RFC.
-        * [You can start with this sample file.](./samples/rfc.md)
-    * A `src/YYYYhN/goals.md` file containing the draft goal listing.
-        * [You can start with this sample file.](./samples/goals.md)
-    * A `src/YYYYhN/not_accepted.md` file containing the list of goals that were not accepted.
-        * [You can start with this sample file.](./samples/not_accepted.md)
-* [ ] Modify SUMMARY.md to include your new milestone with some text like what is shown below.
+| Task      | *Nov–Dec <br> (prev. H2)* | Jan | Feb–Jun         | *Jul <br> (next H2*) |
+|-----------|---------------------------|-----|-----------------|----------------------|
+| [CFP]     | ██████                    | ░░░ |                 |                      |
+| [RFC]     |                           | ███ |                 |                      |
+| [Updates] |                           |     | ███████████████ |                      |
+| [Retro]   |                           |     |                 | ███                  |
 
-Sample `SUMMARY.md` comments from 2025H1:
+### H2 calendar
 
-```
-# ⏳ 2025H1 goal process
-
-- [Overview](./2025h1/README.md)
-- [Proposed goals](./2025h1/goals.md)
-- [Goals not accepted](./2025h1/not_accepted.md)
-```
-
-[Inside Rust]: https://blog.rust-lang.org/inside-rust/
-
-## Receiving PRs
-
-*to be written*
-
-## Preparing the RFC
-
-*to be written*
-
-## Opening the RFC
-
-*to be written*
-
-## Once the RFC is accepted
-
-*to be written*
-
-## Running the goal season
-
-* Every Monday go to Zulip and run:
-    * `@triagebot ping-goals 14 Oct-21`
-* To prepare the monthly blog post:
-    * Run [the `cargo run -- updates` command](./updates.md)
-    * Create a new post in main Rust blog found at [the blog.rust-lang.org repository](https://github.com/rust-lang/blog.rust-lang.org).
-
-
-
-## Finalizing the goal season
+| Task      | *May–Jun <br> (prev. H1)* | Jul | Aug–Dec         | *Jan <br> (next H1)* |
+|-----------|---------------------------|-----|-----------------|----------------------|
+| [CFP]     | ██████                    | ░░░ |                 |                      |
+| [RFC]     |                           | ███ |                 |                      |
+| [Updates] |                           |     | ███████████████ |                      |
+| [Retro]   |                           |     |                 | ███                  |
 
 
+[CFP]: ./cfp.md
+[RFC]: ./prepare_rfc.md
+[Updates]: ./author_updates.md
+[Retro]: ./retro.md

src/admin/samples.md

@@ -0,0 +1 @@
+# Sample texts