@@ -3,11 +3,134 @@
 @; SPDX-License-Identifier: BlueOak-1.0.0
 @; This file is licensed under the Blue Oak Model License 1.0.0.
 
 @(require "scribble-helpers.rkt")
 
-@(require (for-label racket/base))
+@(require (for-label racket/base "../pollen.rkt"))
+
+@section{How I Publish: A Quick Tour}
+
+This isn’t a tutorial, since these steps probably won’t all work on your computer. Think of these
+narrations like me talking while I drive.
+
+@subsection{Creating an article}
+
+Open a terminal window.
+
+@terminal{@cmd{> cd /path/to/thelocalyarn}}
+
+The @tt{make} command provides a high-level control panel for common tasks. Typing just make from
+a terminal window shows a list of options:
+
+@terminal{
+@cmd{> make}
+article     Start a new article from a template
+help        Displays this help screen
+publish     Sync all HTML and PDF stuff to the public web server
+scribble    Rebuild code documentation and update Fossil repo
+web         Rebuild all web content (not PDFs)
+zap         Clear Pollen and Scribble cache, and remove all HTML output
+}
+
+Following the first option in this list, I type @tt{make article}, and enter a post title when
+prompted:
+
+@terminal{
+@cmd{> make article}
+racket -tm util/newpost.rkt
+Enter title: @cmd{My New Post}
+}
+
+The script creates a new @filepath{.poly.pm} file using a normalized version of the title for the
+filename, and opens it in my editor (this is currently hardcoded to use MacVim). When the file pops
+up we see a basic template ready to edit:
+
+@filebox["articles/my-new-post.poly.pm"
+@codeblock|{
+#lang pollen
+ 
+◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
+◊(define-meta draft #t)
+◊(define-meta published "2020-01-18")
+ 
+◊title{My New Post}
+ 
+Write here!
+}|]
+
+At this point I might delete the @tt{◊title} line, since specifying a formal title is optional
+(other than the one needed to generate the filename). I might also add a @racket[define-meta] for
+@tt{series} or @tt{topics}. 
+
+As long as the @racket[define-meta] for @tt{draft} is @racket[#t], the new article will not appear
+in the RSS feed, or in the blog or any series pages.
+
+When satisfied with the post I’ll remove the @racket[define-meta] for @tt{draft}, save it one last
+time, then go back to the terminal:
+
+@terminal{
+@cmd{> make web}
+[lots of output: rebuilds blog pages, keyword index, RSS feed]
+@cmd{> make publish}
+[lots of output: uploads all web content to the server]
+}
+
+The article also needs to be added to the Fossil repository, so revisions to it will be tracked:
+
+@terminal|{
+|@cmd{> fossil add article/my-new-post.poly.pm}
+ADDED  article/my-new-post.poly.pm
+
+|@cmd{> fossil commit -m "Publish ‘My New Post’"}
+Autosync:  https://joel@thelocalyarn.com/code
+Round-trips: 2   Artifacts sent: 0  received: 1
+Pull done, sent: 892  received: 8720  ip: 162.243.186.132
+New_Version: 15507b62416716a3f0be3c444b0fc09aa4364b989140c5788cf679eb0b2463a6
+Autosync:  https://joel@thelocalyarn.com/code
+Round-trips: 2   Artifacts sent: 2  received: 1
+Sync done, sent: 10153  received: 4680  ip: 162.243.186.132
+}|
+
+As you can see, Fossil does an automatic pull before the commit, and another automatic push
+afterwards. This commit is now visible on the public timeline, and the source code for the article
+can now be seen on the public repo at @tt{thelocalyarn.com/code/}.
+
+@subsection{Adding notes to an article}
+
+A few days (or years) after doing the above, I receive an email from Marjorie with commenting on
+@italic{My New Post} and I decide to publish her comments.
+
+I open the article in my editor and add some lines to the end:
+
+@filebox["articles/my-new-post.poly.pm"
+@codeblock|{
+#lang pollen
+ 
+◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
+◊(define-meta published "2020-01-18")
+ 
+◊title{My New Post}
+ 
+It’s a 4⨉4 treated. I got twenty, actually, for the backyard fence.
+
+◊note[#:date "2020-01-23" #:author "Marjorie"]{
+ Hope you sank that thing below the frost line.
+}
+}|]
+
+This looks like a blog-style comment, but the @racket[note] tag function has some special powers
+that typical comments don’t have, as we’ll see in a moment.
+
+I save this, go back to the terminal and do @tt{make web} and @tt{make publish} as before.
+
+Now if you open the article’s permlink, you’ll see the note appears in a “Further Notes” section at
+the bottom — again, just like a normal blog post comment.
+
+But if you go to the Blog section, you’ll see the note appearing in its own space right alongside
+the other articles, as if it were a separate post. It will also appear in a separate entry in the
+RSS feed.
 
-@title{A Tour: Publishing on @italic{The Local Yarn}}
+@subsection{What’s not here yet}
 
-It’s pretty simple.
+Eventually there will be facilities for creating PDF files of individual articles, and print-ready
+PDFs of books containing collections of articles.