diff --git a/docs-src/application-lifecycle.md b/docs-src/application-lifecycle.md
index 1e7c0329..abc2b6fb 100644
--- a/docs-src/application-lifecycle.md
+++ b/docs-src/application-lifecycle.md
@@ -1,5 +1,5 @@
 ## main thread
-The main function, and therefore the main loop,
+The `main` function, and therefore the main loop,
 should run on the main thread. 
 
 ```go
@@ -11,7 +11,7 @@ func init() {
 ```
 
 ## initialisation
-Call `gtk.Init` (or `gtk.InitChack`) before calling
+Call `gtk.Init` (or `gtk.InitCheck`) before calling
 any other gtk functions.
 Typically the program's command-line arguments will
 be passed to `gtk.Init`.
@@ -32,12 +32,14 @@ If an application has only one window,
 then it might terminate when the window is closed.
 
 ```go
+// Connect to the window's "destroy" signal.
 window.Widget().ConnectDestroy(func() {
     gtk.MainQuit()
 })
 ``` 
 
-This may be written more succinctly, like this.
+As the callback's signature matches that of `gtk.MainQuit`,
+this may be written more succinctly like this.
 
 ```go
 window.Widget().ConnectDestroy(gtk.MainQuit)
diff --git a/docs-src/build-tags.md b/docs-src/build-tags.md
index aaadd6eb..edf9db23 100644
--- a/docs-src/build-tags.md
+++ b/docs-src/build-tags.md
@@ -1,7 +1,7 @@
 gobbi uses Go 
 [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints)
 to allow targetting of specific library versions.
-This means that when using Go build tools
+This means that when using Go tools
 (such as `go build` and `go run`)
 to build a gobbi application,
 use of the `-tags` flag will usually be necessary.
@@ -26,6 +26,13 @@ is only available from gtk 3.10 onwards.
 So to use it, a tag specifying 3.10 (or a later version)
 is required.
 
+
+A tag such as `gtk_3.10` is formed of three parts.
+
+- the library name, `gtk`
+- an underscore, `_`
+- the minimum library version, `3.10`
+
 ```bash
 go build -tags gtk_3.10 my_app.go
 ```
@@ -55,6 +62,7 @@ The relevant setting is `Go: Build Tags`.
 ### goland
 In the `Settings...` dialog, the relevant setting can
 be found under
+
 - Go
-  - Vendoring & Build Tags
-    - Custom tags
+   - Vendoring & Build Tags
+      - Custom tags
diff --git a/docs-src/casting.md b/docs-src/casting.md
index 563c606c..bea2a9a2 100644
--- a/docs-src/casting.md
+++ b/docs-src/casting.md
@@ -1,6 +1,6 @@
 Gtk classes derive in a hierarchy from the GObject class.
 
-In gobbi's implementation of GOBject's classes,
+In gobbi's implementation of GObject's classes,
 each class does not directly extend
 (or embed in Go terms)
 its ancestor classes.
@@ -21,7 +21,7 @@ label := gtk.LabelNew("a label")
 window.Add(label)   // <-- ERROR
 ``` 
 
-`gtk.Window` does not directly have a `Add` method.
+`gtk.Window` does not directly have an `Add` method.
 The `Add` method is a member of `gtk.Container`,
 which is an ancestor of `gtk.Window`.
 
@@ -50,7 +50,7 @@ widget2 := gtk.WindowNew().Widget()
 
 # downcasting
 Downcasting operates in the other direction,
-from a class to a derived class,
+from a class to a derived class.
 
 Downcasting is less common that upcasting.
 It is potentially quite dangerous, in that it makes
diff --git a/docs-src/getting-started.md b/docs-src/getting-started.md
index c532be3d..47c703b9 100644
--- a/docs-src/getting-started.md
+++ b/docs-src/getting-started.md
@@ -4,7 +4,7 @@
     * debian/ubuntu packages -
         `libatk1.0-dev libcairo2-dev libglib2.0-dev
         libgtk-3-dev libpango1.0-dev`
-    * note that dev libraries are required because pkg-config
+    * note that dev versions of the libraries are required because pkg-config
         and headers are necessary
 * C compiler, and a linker
     * required because of the use of cgo
@@ -17,12 +17,15 @@
 * `./gobbi example simple_window`
     * Be patient.
         The first `go build` or `go run` will take quite a while,
-        perhaps a few minutes.
-        Subsequent builds of applications will be a *lot* quicker
-        as cached gobbi packages will be used by the Go commands. 
+        perhaps a minute.
+        Subsequent builds of applications will be a lot quicker
+        as cached gobbi packages will be used by the Go tools. 
 
 Run `./gobbi examples` for a list of the available examples.
 
+(The gobbi script supports other commands,
+but they are only needed for development of gobbi itself.)
+
 ## use in an application
 Using gobbi in an application in no different to using
 most other libraries.
@@ -38,6 +41,11 @@ Then import a package such as gtk.
 import "github.com/pekim/gobbi/lib/gtk"
 ```
 
+[Application lifecycle](application-lifecycle.html)
+describes the minimal apis needed to build
+an application that will create a window.
+
+
 ## build tags
 It will often be necessary to build gobbi applications
 with [build tags](../build-tags).
diff --git a/docs-src/goroutines.md b/docs-src/goroutines.md
index acd3f622..ed6a75dd 100644
--- a/docs-src/goroutines.md
+++ b/docs-src/goroutines.md
@@ -1,6 +1,6 @@
 All calls to gtk functions should be performed on
 the main thread.
-To perform such a call from a goroutine,
+To perform such calls from a goroutine,
 use `glib.IdleAdd` to schedule invocation of a
 callback function on the main thread. 
 
diff --git a/docs-src/gvalue.md b/docs-src/gvalue.md
index 3583065d..46a15e8e 100644
--- a/docs-src/gvalue.md
+++ b/docs-src/gvalue.md
@@ -1,4 +1,5 @@
-The gobject library's `GValue` type is represented by
+The gobject library's `GValue` type is represented
+in gobbi by
 `gobject.Value`.
 
 See the [list](https://github.com/pekim/gobbi/blob/master/example/list/main.go)
diff --git a/docs-src/signal-handling.md b/docs-src/signal-handling.md
index f270b536..344fc843 100644
--- a/docs-src/signal-handling.md
+++ b/docs-src/signal-handling.md
@@ -10,16 +10,21 @@ information.
 
 ```go
 button := gtk.ButtonNewWithLabel("a button")
+
+// enable emitting of motion events
 button.Widget().SetEvents(int32(gdk.GDK_POINTER_MOTION_MASK))
+
 button.Widget().ConnectMotionNotifyEvent(
     func(event *gdk.EventMotion) bool {
         fmt.Println(event.Y, event.Y)
         return false
-    })
+    }
+)
 ```
 
-Remember that it may be necessary to upcast to access the
-desired connect method.
+Remember that it may be necessary to
+[upcast](casting.html)
+to access the desired connect method.
 
 ## disconnecting
 All of the `Connect...` methods return a handler id.
@@ -36,16 +41,18 @@ The id may be used later to disconnect the handler.
 ```
 
 ## notify signal for a single property
-`ConnectNotifyProperty` connects the callback
+`ConnectNotifyProperty` connects a callback
 to the `notify` signal
 for a specific property of an Object.
 
-For example, to connect to the notify signal
-for the "title" property of a window.
+This is an example of connecting to the notify signal
+for a window's
+[title property](https://developer.gnome.org/gtk3/stable/GtkWindow.html#GtkWindow--title).
 
 ```go
     window := gtk.WindowNew(...)
 
+    // connect to the "notify::title" signal
     window.Object().ConnectNotifyProperty(
         "title", func(pspec *gobject.ParamSpec,
     ) {
@@ -53,9 +60,6 @@ for the "title" property of a window.
     })
 ```
 
-In that example it is the `notify::title` signal
-that is being connected to.
-
 The returned value represents the connection,
 and may be passed to `DisconnectNotify` to remove it.
 
diff --git a/docs-src/variadic-functions.md b/docs-src/variadic-functions.md
index e1a3c7d4..c080712f 100644
--- a/docs-src/variadic-functions.md
+++ b/docs-src/variadic-functions.md
@@ -15,10 +15,13 @@ This is because `fmt.Sprint` is used to format a string
 before passing it as the last argument
 to the wrapped C function.
 
-A much simplified representation of such a function might
-help to make this clearer.
+A much simplified representation of such a
+gobbi function might help to make this clearer.
 ```go
-func SomeRepresentativeFunction(
+package gtk
+
+// a gobbi function
+func SomeFormatFunction(
 	a string, b int,
 	format string, args ...interface{},
 ) {
@@ -28,7 +31,17 @@ func SomeRepresentativeFunction(
 	formattedString := fmt.Sprintf(format, args...)
 	c_formattedString := C.String(formattedString)
 
-	C.some_representative_function(c_a, c_b, c_formattedString)
+	C.some_format_function(c_a, c_b, c_formattedString)
+}
+
+// ----------------------------- //
+
+// some application code
+func aFunction () {
+    gtk.SomeFormatFunction(
+        "a string", 123,
+        "the %s is %d", "answer", 42,
+    )
 }
 ```
 
@@ -38,7 +51,7 @@ because it would be impractical to automatically
 generate code that would support them.
 
 ### array functions
-In some cases there is another function that accepts an array
+In some cases there is an alternative function that accepts an array
 as the final argument instead.
 For example
 [gtk_list_store_new](https://developer.gnome.org/gtk3/stable/GtkListStore.html#gtk-list-store-new)
@@ -47,7 +60,7 @@ is not supported, but
 is supported as [gtk.ListStoreNewv](https://godoc.org/github.com/pekim/gobbi/lib/gtk#ListStoreNewv).
 
 ### multiple functions 
-There are other variadac functions that do not have an array
+There are other variadac functions that may not have an array
 equivalent version, but their functionality
 can be achieved through a combination of functions.
 
diff --git a/docs/api.html b/docs/api.html
index d4f6f579..784c7bd6 100644
--- a/docs/api.html
+++ b/docs/api.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
diff --git a/docs/application-lifecycle.html b/docs/application-lifecycle.html
index 00db8cfb..4ebf23ca 100644
--- a/docs/application-lifecycle.html
+++ b/docs/application-lifecycle.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
@@ -68,7 +68,7 @@
                 <h1>Application lifecycle</h1>
                 <h2>main thread</h2>
 
-<p>The main function, and therefore the main loop,
+<p>The <code>main</code> function, and therefore the main loop,
 should run on the main thread.</p>
 
 <pre><code class="language-go">func init() {
@@ -80,7 +80,7 @@ <h2>main thread</h2>
 
 <h2>initialisation</h2>
 
-<p>Call <code>gtk.Init</code> (or <code>gtk.InitChack</code>) before calling
+<p>Call <code>gtk.Init</code> (or <code>gtk.InitCheck</code>) before calling
 any other gtk functions.
 Typically the program&rsquo;s command-line arguments will
 be passed to <code>gtk.Init</code>.</p>
@@ -100,12 +100,14 @@ <h2>termination</h2>
 <p>If an application has only one window,
 then it might terminate when the window is closed.</p>
 
-<pre><code class="language-go">window.Widget().ConnectDestroy(func() {
+<pre><code class="language-go">// Connect to the window's &quot;destroy&quot; signal.
+window.Widget().ConnectDestroy(func() {
     gtk.MainQuit()
 })
 </code></pre>
 
-<p>This may be written more succinctly, like this.</p>
+<p>As the callback&rsquo;s signature matches that of <code>gtk.MainQuit</code>,
+this may be written more succinctly like this.</p>
 
 <pre><code class="language-go">window.Widget().ConnectDestroy(gtk.MainQuit)
 </code></pre>
diff --git a/docs/build-tags.html b/docs/build-tags.html
index 676e8f49..269546ec 100644
--- a/docs/build-tags.html
+++ b/docs/build-tags.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
@@ -69,7 +69,7 @@ <h1>Build tags</h1>
                 <p>gobbi uses Go
 <a href="https://golang.org/pkg/go/build/#hdr-Build_Constraints">build tags</a>
 to allow targetting of specific library versions.
-This means that when using Go build tools
+This means that when using Go tools
 (such as <code>go build</code> and <code>go run</code>)
 to build a gobbi application,
 use of the <code>-tags</code> flag will usually be necessary.</p>
@@ -96,6 +96,14 @@ <h2>tags targetting versions</h2>
 So to use it, a tag specifying 3.10 (or a later version)
 is required.</p>
 
+<p>A tag such as <code>gtk_3.10</code> is formed of three parts.</p>
+
+<ul>
+<li>the library name, <code>gtk</code></li>
+<li>an underscore, <code>_</code></li>
+<li>the minimum library version, <code>3.10</code></li>
+</ul>
+
 <pre><code class="language-bash">go build -tags gtk_3.10 my_app.go
 </code></pre>
 
@@ -126,10 +134,19 @@ <h3>vs code</h3>
 <h3>goland</h3>
 
 <p>In the <code>Settings...</code> dialog, the relevant setting can
-be found under
-- Go
-  - Vendoring &amp; Build Tags
-    - Custom tags</p>
+be found under</p>
+
+<ul>
+<li>Go
+
+<ul>
+<li>Vendoring &amp; Build Tags
+
+<ul>
+<li>Custom tags</li>
+</ul></li>
+</ul></li>
+</ul>
 
             </div>
         </div>
diff --git a/docs/casting.html b/docs/casting.html
index 963b477b..f24a59f2 100644
--- a/docs/casting.html
+++ b/docs/casting.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
@@ -68,7 +68,7 @@
                 <h1>Casting</h1>
                 <p>Gtk classes derive in a hierarchy from the GObject class.</p>
 
-<p>In gobbi&rsquo;s implementation of GOBject&rsquo;s classes,
+<p>In gobbi&rsquo;s implementation of GObject&rsquo;s classes,
 each class does not directly extend
 (or embed in Go terms)
 its ancestor classes.
@@ -89,7 +89,7 @@ <h1>upcasting</h1>
 window.Add(label)   // &lt;-- ERROR
 </code></pre>
 
-<p><code>gtk.Window</code> does not directly have a <code>Add</code> method.
+<p><code>gtk.Window</code> does not directly have an <code>Add</code> method.
 The <code>Add</code> method is a member of <code>gtk.Container</code>,
 which is an ancestor of <code>gtk.Window</code>.</p>
 
@@ -118,7 +118,7 @@ <h1>upcasting</h1>
 <h1>downcasting</h1>
 
 <p>Downcasting operates in the other direction,
-from a class to a derived class,</p>
+from a class to a derived class.</p>
 
 <p>Downcasting is less common that upcasting.
 It is potentially quite dangerous, in that it makes
diff --git a/docs/getting-started.html b/docs/getting-started.html
index 1ef8d248..f63859c7 100644
--- a/docs/getting-started.html
+++ b/docs/getting-started.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
@@ -76,7 +76,7 @@ <h2>pre-requisites</h2>
 <li>debian/ubuntu packages -
 <code>libatk1.0-dev libcairo2-dev libglib2.0-dev
 libgtk-3-dev libpango1.0-dev</code></li>
-<li>note that dev libraries are required because pkg-config
+<li>note that dev versions of the libraries are required because pkg-config
 and headers are necessary</li>
 </ul></li>
 <li>C compiler, and a linker
@@ -98,14 +98,17 @@ <h2>running examples</h2>
 <ul>
 <li>Be patient.
 The first <code>go build</code> or <code>go run</code> will take quite a while,
-perhaps a few minutes.
-Subsequent builds of applications will be a <em>lot</em> quicker
-as cached gobbi packages will be used by the Go commands.</li>
+perhaps a minute.
+Subsequent builds of applications will be a lot quicker
+as cached gobbi packages will be used by the Go tools.</li>
 </ul></li>
 </ul>
 
 <p>Run <code>./gobbi examples</code> for a list of the available examples.</p>
 
+<p>(The gobbi script supports other commands,
+but they are only needed for development of gobbi itself.)</p>
+
 <h2>use in an application</h2>
 
 <p>Using gobbi in an application in no different to using
@@ -122,6 +125,10 @@ <h2>use in an application</h2>
 <pre><code class="language-go">import &quot;github.com/pekim/gobbi/lib/gtk&quot;
 </code></pre>
 
+<p><a href="application-lifecycle.html">Application lifecycle</a>
+describes the minimal apis needed to build
+an application that will create a window.</p>
+
 <h2>build tags</h2>
 
 <p>It will often be necessary to build gobbi applications
diff --git a/docs/goroutines.html b/docs/goroutines.html
index 9a0c2d52..2369f310 100644
--- a/docs/goroutines.html
+++ b/docs/goroutines.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
@@ -68,7 +68,7 @@
                 <h1>Goroutines</h1>
                 <p>All calls to gtk functions should be performed on
 the main thread.
-To perform such a call from a goroutine,
+To perform such calls from a goroutine,
 use <code>glib.IdleAdd</code> to schedule invocation of a
 callback function on the main thread.</p>
 
diff --git a/docs/gvalue.html b/docs/gvalue.html
index 57010ca5..25f6831e 100644
--- a/docs/gvalue.html
+++ b/docs/gvalue.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
@@ -66,7 +66,8 @@
 
             <div class="content">
                 <h1>gobject.Value</h1>
-                <p>The gobject library&rsquo;s <code>GValue</code> type is represented by
+                <p>The gobject library&rsquo;s <code>GValue</code> type is represented
+in gobbi by
 <code>gobject.Value</code>.</p>
 
 <p>See the <a href="https://github.com/pekim/gobbi/blob/master/example/list/main.go">list</a>
diff --git a/docs/index.html b/docs/index.html
index 8a027897..ec1feb81 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
diff --git a/docs/reference-counting.html b/docs/reference-counting.html
index a375f8ae..6b85939b 100644
--- a/docs/reference-counting.html
+++ b/docs/reference-counting.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
diff --git a/docs/signal-handling.html b/docs/signal-handling.html
index 00a0cc33..14769ca1 100644
--- a/docs/signal-handling.html
+++ b/docs/signal-handling.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
@@ -78,16 +78,21 @@ <h2>connecting</h2>
 information.</p>
 
 <pre><code class="language-go">button := gtk.ButtonNewWithLabel(&quot;a button&quot;)
+
+// enable emitting of motion events
 button.Widget().SetEvents(int32(gdk.GDK_POINTER_MOTION_MASK))
+
 button.Widget().ConnectMotionNotifyEvent(
     func(event *gdk.EventMotion) bool {
         fmt.Println(event.Y, event.Y)
         return false
-    })
+    }
+)
 </code></pre>
 
-<p>Remember that it may be necessary to upcast to access the
-desired connect method.</p>
+<p>Remember that it may be necessary to
+<a href="casting.html">upcast</a>
+to access the desired connect method.</p>
 
 <h2>disconnecting</h2>
 
@@ -105,15 +110,17 @@ <h2>disconnecting</h2>
 
 <h2>notify signal for a single property</h2>
 
-<p><code>ConnectNotifyProperty</code> connects the callback
+<p><code>ConnectNotifyProperty</code> connects a callback
 to the <code>notify</code> signal
 for a specific property of an Object.</p>
 
-<p>For example, to connect to the notify signal
-for the &ldquo;title&rdquo; property of a window.</p>
+<p>This is an example of connecting to the notify signal
+for a window&rsquo;s
+<a href="https://developer.gnome.org/gtk3/stable/GtkWindow.html#GtkWindow--title">title property</a>.</p>
 
 <pre><code class="language-go">    window := gtk.WindowNew(...)
 
+    // connect to the &quot;notify::title&quot; signal
     window.Object().ConnectNotifyProperty(
         &quot;title&quot;, func(pspec *gobject.ParamSpec,
     ) {
@@ -121,9 +128,6 @@ <h2>notify signal for a single property</h2>
     })
 </code></pre>
 
-<p>In that example it is the <code>notify::title</code> signal
-that is being connected to.</p>
-
 <p>The returned value represents the connection,
 and may be passed to <code>DisconnectNotify</code> to remove it.</p>
 
diff --git a/docs/style.css b/docs/style.css
index 5c26ad9a..994100ec 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -8,7 +8,7 @@ body {
     flex-direction: column;
 
     font-family: "Helvetica Neue Light", "HelveticaNeue-Light", "Helvetica Neue", Calibri, Helvetica, Arial, sans-serif;
-    font-size: 18px;
+    font-size: 16px;
     line-height: 1.5;
 }
 
@@ -84,7 +84,7 @@ nav ol li {
 }
 
 .content {
-    max-width: 50em;
+    max-width: 45em;
 
     margin-left: 15em;
     padding-left: 2em;
diff --git a/docs/variadic-functions.html b/docs/variadic-functions.html
index 75b8b66e..5edd8025 100644
--- a/docs/variadic-functions.html
+++ b/docs/variadic-functions.html
@@ -42,9 +42,6 @@
             <li>
                 <a href="goroutines.html">Goroutines</a>
             </li>
-            <li>
-                <a href="gvalue.html">gobject.Value</a>
-            </li>
             <li>
                 <a href="casting.html">Casting</a>
             </li>
@@ -54,6 +51,9 @@
             <li>
                 <a href="variadic-functions.html">Variadic functions</a>
             </li>
+            <li>
+                <a href="gvalue.html">gobject.Value</a>
+            </li>
             <li>
                 <a href="reference-counting.html">Reference counting</a>
             </li>
@@ -84,10 +84,13 @@ <h2>format functions</h2>
 before passing it as the last argument
 to the wrapped C function.</p>
 
-<p>A much simplified representation of such a function might
-help to make this clearer.</p>
+<p>A much simplified representation of such a
+gobbi function might help to make this clearer.</p>
+
+<pre><code class="language-go">package gtk
 
-<pre><code class="language-go">func SomeRepresentativeFunction(
+// a gobbi function
+func SomeFormatFunction(
 	a string, b int,
 	format string, args ...interface{},
 ) {
@@ -97,7 +100,17 @@ <h2>format functions</h2>
 	formattedString := fmt.Sprintf(format, args...)
 	c_formattedString := C.String(formattedString)
 
-	C.some_representative_function(c_a, c_b, c_formattedString)
+	C.some_format_function(c_a, c_b, c_formattedString)
+}
+
+// ----------------------------- //
+
+// some application code
+func aFunction () {
+    gtk.SomeFormatFunction(
+        &quot;a string&quot;, 123,
+        &quot;the %s is %d&quot;, &quot;answer&quot;, 42,
+    )
 }
 </code></pre>
 
@@ -109,7 +122,7 @@ <h2>unsupported variadic functions</h2>
 
 <h3>array functions</h3>
 
-<p>In some cases there is another function that accepts an array
+<p>In some cases there is an alternative function that accepts an array
 as the final argument instead.
 For example
 <a href="https://developer.gnome.org/gtk3/stable/GtkListStore.html#gtk-list-store-new">gtk_list_store_new</a>
@@ -119,7 +132,7 @@ <h3>array functions</h3>
 
 <h3>multiple functions</h3>
 
-<p>There are other variadac functions that do not have an array
+<p>There are other variadac functions that may not have an array
 equivalent version, but their functionality
 can be achieved through a combination of functions.</p>
 
diff --git a/internal/cmd/docs/main.go b/internal/cmd/docs/main.go
index 51d6b9d7..e63046d3 100644
--- a/internal/cmd/docs/main.go
+++ b/internal/cmd/docs/main.go
@@ -23,10 +23,10 @@ var pages = []Page{
 	Page{File: "application-lifecycle", Title: "Application lifecycle"},
 	Page{File: "build-tags", Title: "Build tags"},
 	Page{File: "goroutines", Title: "Goroutines"},
-	Page{File: "gvalue", Title: "gobject.Value"},
 	Page{File: "casting", Title: "Casting"},
 	Page{File: "signal-handling", Title: "Signal handling"},
 	Page{File: "variadic-functions", Title: "Variadic functions"},
+	Page{File: "gvalue", Title: "gobject.Value"},
 	Page{File: "reference-counting", Title: "Reference counting"},
 	Page{File: "api", Title: "API docs"},
 }