howto/git.md

-# git.torproject.org and associated services
-
-[[_TOC_]]
-
-## Overview
-
 Our git setup consists of three interdependent services:
 
  * git-rw.torproject.org:  ssh accessible and writeable git repositories
@@ -13,6 +7,10 @@ Our git setup consists of three interdependent services:
 When a developer pushes to git-rw, the repository is mirrored to git and so
 made available via the gitweb service.
 
+[[_TOC_]]
+
+# Howto
+
 ## Regular repositories
 
 ### Creating a new repository
@@ -329,7 +327,26 @@ similarly.
 Note that repos can also be migrated (and archived) to GitLab, see
 [the GitLab migration procedure](howto/gitlab/#how-to-migrate-a-git-repository-from-legacy-to-gitlab) for details.
 
-## Admin details
+## Potential problems to solve
+
+### gitweb out of sync
+
+If vineale is down for an extended period of time, it's a good idea to trigger
+a re-sync of all the repositories to ensure that the latest version is available
+to clone from the anonymous endpoints.
+
+Create an empty commit in the gitolite-admin.git repository using:
+
+```
+git commit -m "trigger resync" --allow-empty
+```
+
+and push this commit. This will run through the post-commit hook that includes
+syncing everything.
+
+# Reference
+
+## Design
 
 git-rw runs on `cupani.torproject.org` and runs as the git user. Users in the
 gitolite (gid 1504) group can become the git user. The gitolite installation
@@ -362,20 +379,3 @@ and only gitolite configuration restricts further access.
 Access to push to this repository is controlled by the
 `gitolite-admin` repository entry in the gitolite configuration file,
 and not by LDAP groups.
-
-## Potential problems to solve
-
-### gitweb out of sync
-
-If vineale is down for an extended period of time, it's a good idea to trigger
-a re-sync of all the repositories to ensure that the latest version is available
-to clone from the anonymous endpoints.
-
-Create an empty commit in the gitolite-admin.git repository using:
-
-```
-git commit -m "trigger resync" --allow-empty
-```
-
-and push this commit. This will run through the post-commit hook that includes
-syncing everything.