github-management: add improvements to docs

2 files changed, 29 insertions, 13 deletions

diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md
index acff41d3..803d9b1c 100644
--- a/github-management/kubernetes-repositories.md
+++ b/github-management/kubernetes-repositories.md
@@ -183,13 +183,15 @@ from the above procedure:
 
   * The repository **must** have an initial empty commit. The contents of the
   repo will be populated from staging by the [publishing-bot].
+  * Grant the [@kubernetes/stage-bots] team admin access to the repo.
   * Setup branch protection and enable access to the
   `stage-bots` team by adding the repo in
   [`prow/config.yaml`](https://git.k8s.io/test-infra/prow/config.yaml). See
   [kubernetes/test-infra#9292](https://github.com/kubernetes/test-infra/pull/9292)
   for an example.
-  * Once the repo has been created, ask [@nikhita] to update the
-  [publishing-bot] configuration to include the repo.
+  * Once the repo has been created, add the repo to
+  [`hack/fetch-all-latest-and-push.sh`](https://git.k8s.io/publishing-bot/hack/fetch-all-latest-and-push.sh)
+  in the [publishing-bot] repo.
 
 <!-- TODO: Add suggestions for how to migrate existing repos -->
 
@@ -234,6 +236,8 @@ steps:
   * All webhooks, apps, integrations or services are removed
   * GitHub Pages are disabled
   * The repo is marked as archived using [GitHub's archive feature]
+  * Remove all teams associated with the repo
+  * Remove the repo from [sigs.yaml]
   * The removal is announced on the kubernetes-dev mailing list and community
     meeting
 
@@ -311,4 +315,5 @@ https://help.github.com/articles/archiving-a-github-repository/
 [team guidance]: /github-management/org-owners-guide.md#team-guidance
 [SIG Repository]: #sig-repositories
 [publishing-bot]: https://github.com/kubernetes/publishing-bot
-[@nikhita]: https://github.com/nikhita
+[@kubernetes/stage-bots]: https://github.com/orgs/kubernetes/teams/stage-bots
+[sigs.yaml]: /sigs.yaml
diff --git a/github-management/org-owners-guide.md b/github-management/org-owners-guide.md
index bd71de82..476c71f5 100644
--- a/github-management/org-owners-guide.md
+++ b/github-management/org-owners-guide.md
@@ -82,19 +82,30 @@ for all orgs going forward.  Notable discrepancies at the moment:
 
 Guidelines on how to create and structure teams are described below:
 
-- Teams should not have any `maintainers` and everyone who should be part of
-the team should be added in the `members` list.
-  - Note that because of how the GiHub API works, org admins still need to be
-    in the `maintainers` list for the teams they are a part of.
+#### Structure
+
+**Renaming a team**:
+
+To rename a team, add the `previously: <old-team-name>` field to the team
+and rename the `name` of the team to the new name.
+
+**Creating a team**:
+
+- Unless a member is part of the [@kubernetes/owners] team, they needed to be
+  added to the `members` list in the team. Members of the
+  [@kubernetes/owners] team *must* be added to the `maintainers` list because
+  of how the GitHub API works.
 - The `privacy` of a team *must* be `closed`.
-- A new team can be created or a member can be added to a team by
+
+#### Process
+
+A new team can be created or a member can be added to a team by
 creating a PR against the [kubernetes/org] repo. The PR must be
 approved by the relevant `OWNERS` or the SIG leads.
-  - For example, addition of a member to `foo-maintainers` must be approved
-    by the `OWNERS` of the repo `foo` or the leads of the SIG associated
-    with the repo.
-- To rename a team, add the `previously: <old-team-name>` field to the team
-and rename the `name` of the team to the new name.
+
+For example, addition of a member to `foo-maintainers` must be approved
+by the `OWNERS` of the repo `foo` or the leads of the SIG associated
+with the repo.
 
 ## Project Board Guidance