Improve contributor documentation

CONTRIBUTING.md

@@ -18,11 +18,11 @@ All PRs and branches are built using GitHub Actions, covering a large set of per
 
 Fairly standard pull request workflow. Please do *not* rebase commits that you've already pushed to a non-draft pull request unless explicitly requested. It's also very helpful if you toggle on the "Allow edits and access to secrets by maintainers" check box. There are no secrets, so you aren't leaking anything. What this does is allows maintainers to push last-minute trivial fixes to your PR (e.g. scalafmt) and ensure it can be merged with appropriate attribution.
 
-We maintain multiple primary branches within the Cats Effect repository. The active branches are dependent on the most recent release. The following examples assume the most recent releases were 3.4.1 and 2.5.7 (in the 2.x and 3.x lineages, respective). For those most recent releases, the active branches will be as follows:
+We maintain multiple primary branches within the Cats Effect repository. The active branches are dependent on the most recent release. The following examples assume the most recent releases were 3.5.4 and 2.5.7 (in the 2.x and 3.x lineages, respectively). For those most recent releases, the active branches will be as follows:
 
 - `series/3.x` (default)
   + Any *binary compatible* changes on top of a 3.x version which are not source- or forward-compatible
-- `series/3.4.x`
+- `series/3.5.x`
   + Any *source-* and *forward-compatible* changes on top of the latest major/minor version in the 3.x lineage
 - `series/2.x`
   + Any *binary compatible* changes on top of a 2.x version which are not source- or forward-compatible
@@ -32,10 +32,12 @@ We maintain multiple primary branches within the Cats Effect repository. The act
   + Don't work on top of this branch
 - `docs`
   + The shared website definition (including adopters list, main page, etc)
-
-When in doubt, just target your work against `series/3.x`. If you're *very* certain that your changes will be source- *and* forward-compatible, it's safe to target the latest major/minor series (e.g. `series/3.4.x`). Note that forward-compatibility means that you cannot *add or remove* an API, while backward-compatibility means you cannot *remove* an API.
 
-Most releases will be made from the major/minor series branch (e.g. `series/3.4.x`) unless we've determined that it's time to release the next full minor version. With each patch release, we will pull request the major/minor series branch back into the full major branch (e.g. `series/3.x`) to ensure that changes are incorporated. This process is another reason to avoid rebasing or cherry picking already-pull-requested work, since doing so can cause conflicts.
+When in doubt, just target your work against `series/3.x`. If you're *very* certain that your changes will be source- *and* forward-compatible, it's safe to target the latest major/minor series (e.g. `series/3.5.x`). Note that forward-compatibility means that you cannot *add or remove* an API, while backward-compatibility means you cannot *remove* an API.
+
+With documentation changes (both Scaladoc and Markdown documentation in `/docs`), target the *earliest* maintained branch to which those changes are relevant. For example, if a method already exists in `series/3.5.x`, documentation about it should also go into `series/3.5.x`. On the other hand, if that method was only added in `series/3.x`, its documentation should go into `series/3.x`.
+
+Most releases will be made from the major/minor series branch (e.g. `series/3.5.x`) unless we've determined that it's time to release the next full minor version. With each patch release, we will pull request the major/minor series branch back into the full major branch (e.g. `series/3.x`) to ensure that changes are incorporated. This process is another reason to avoid rebasing or cherry picking already-pull-requested work, since doing so can cause conflicts.
 
 ## Licensing
 

RELEASING.md

@@ -1,18 +1,18 @@
 # Release procedure
 
-1. Draft a new release.
-1. Create a new tag with the appropriate name (e.g. v3.5.1); also name the release accordingly.
-1. Make sure you're targeting the appropriate branch! (probably the minor branch)
-1. "Generate new release notes"
-1. edit edit edit
+1. Press the "Draft a new release" button in GitHub.
+1. Create a new tag with the appropriate name (e.g. v3.5.1); also name the release in GitHub accordingly.
+1. Make sure you're targeting the appropriate branch! (Probably the minor branch.)
+1. Press the "Generate new release notes" button in GitHub.
+1. Manually edit the generated release notes:
    - Increment and transliterate the release counter
    - Cargo-cult the old release notes header from the last minor release (including any warnings)
    - Add any special notes to the release header (any major changes or fixes that need calling out)
    - Fix up any formatting or PRs that got sorted to the wrong category
    - Double-check PR attributions (collaborations, hand-offs, etc.)
    - Just make it look nice :)
-1. Publish the release.
-1. Wait for all the CI madness to happen, for the release to announced to Discord, and for the artifacts to sync to Maven Central.
+1. Press the "Publish release" green button in GitHub.
+1. Wait for all the CI madness to happen, for the release to announced to Discord, and for the artifacts to sync to Maven Central (all of this should happen automatically).
 1. Make sure you're locally updated and on the right major/minor branch (this is the same branch as step 3).
 1. Run the following script to open two PRs to (1) update the version in the README/docs of the minor branch and then (2) merge the minor branch into the major branch. This script currently works only for patch releases and not for minor releases, milestones, or release candidates, which need special handling.