diff --git a/README.md b/README.md
index d851e51..fd7a062 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,18 @@
 # repo2html
 
-**repo2html** generates static HTML pages for browsing the contents of a Git repository.
+generates static html pages for browsing the contents of a git repository.
 
 ## basic usage
 
-`repo2html DESTINATION`
+`repo2html <destination>`
 
-Assuming the current directory is a Git repository, this command populates *DESTINATION* with HTML files that provide a web-browsable view of the contents of the git repository.
+run from a git repository, this command populates the directory `<destination>` with html files that provide a web-browsable view of the contents of repository.
 
-Note: changes must be at least committed before they will appear in the HTML output.
-More precisely: the HTML output represents the state of the HEAD commit, not that of the current work-tree (if any).
+note: changes must be at least committed before they will appear in the html output.
+more precisely: the html output represents the state of the `HEAD` commit, not that of the current work-tree.
 
-You may also cause this HTML directory to be automatically updated upon every `git push`, by invoking *repo2html* from a *Git hook*.
-We describe how to use this technique to [build a static git forge](build-a-git-forge.md.html).
+you may also cause this html directory to be automatically updated upon every `git push`, by invoking repo2html from a git hook.
+we describe how to use this technique to [build a static git forge](build-a-git-forge.md.html).
 
 ## features
 
diff --git a/build-a-git-forge.md b/build-a-git-forge.md
index d01ff27..ddc5b0a 100644
--- a/build-a-git-forge.md
+++ b/build-a-git-forge.md
@@ -1,28 +1,29 @@
 # how to use repo2html to build a git forge
 
-This document describes how one might use [repo2html](index.html) (this project) together with a webserver and some configuration to build a static *git forge*.
+this document describes how one might use [repo2html](index.html) (this project) together with a webserver and some configuration to build a static git forge.
 
-A **git forge** is a website that presents one or more git repositories for visitors to browse,
+a git forge is a website that presents one or more git repositories for visitors to browse,
 and also allows them to `git clone`, `pull`, and optionally `push` commits to and from those repositories,
 while automatically updating the browsable representation.
 
-Some extant *git forge* services include:
-GitHub,
-BitBucket,
-[GitLab](https://gitlab.com/),
-SourceForge,
-[Sourcehut](https://sourcehut.org/), and
-[Codeberg](https://codeberg.org/).
+some extant *git forge* services include:
+github,
+bitbucket,
+[gitlab](https://gitlab.com/),
+sourceforge,
+[sourcehut](https://sourcehut.org/), and
+[codeberg](https://codeberg.org/).
 
-Software that can be used to build a self-hosted git forge includes:
+software that can be used to build a self-hosted git forge includes:
 self-hosted [gitlab](https://about.gitlab.com/install/),
 [gogs](https://gogs.io/),
 [gitea](https://gitea.io/),
 [cgit](https://git.zx2c4.com/cgit/), and
 [gitweb](https://git-scm.com/book/en/v2/Git-on-the-Server-GitWeb).
 
-Since **repo2html** is configured herein to output updated HTML files only in response to a `git push`, the git forge described here requires no complex server software like the ones above.
-Its webserver is configured to serve static html files from disk.
+the git forge described here requires no continuously-running software beyond a simple webserver.
+we configure repo2html to output updated html files only in response to a `git push`,
+which the webserver then serves from disk.
 
 ## quickstart