#lang scribble/manual
@; SPDX-License-Identifier: BlueOak-1.0.0
@; This file is licensed under the Blue Oak Model License 1.0.0.
@(require "scribble-helpers.rkt"
racket/runtime-path
(for-label "../pollen.rkt"))
@(require (for-label racket/base))
@title{Basic Notions}
@section[#:tag "design-goals"]{Design Goals}
The design of @italic{The Local Yarn} is guided by requirements that have evolved since I started
the site in 1999. I enumerate them here because they explain why the code is necessarily more
complicated than a typical blog:
@itemlist[
@item{@bold{The writing will publish to two places from the same source: the web server, and the
bookshelf.} The web server, because it’s a fun, fast way to publish writing and code to the whole
world (you knew that already); but also on bookshelves, because
@ext-link["https://thelocalyarn.com/excursus/secretary/posts/web-books.html"]{a web server is like
a projector}, and I want to be able to turn it off someday and still have something to show for all
my work. Plus, I just like printed books.}
@item{@bold{Changes are part of the content.} I like to revisit, resurface and amend things I’ve
written before. Views change, new ideas come along. In a typical blog the focus is always at
whatever’s happening at the head of the time stream; an addendum to an older post is, for all
practical purposes, invisible and nearly useless. I want every published edit to an article to be
findable and linkable. I want addenda to be extremely visible. These addenda should also be able to
mark major shifts in the author’s own perspective on what they originally wrote.}
@item{@bold{The system will gracefully accomodate experimentation.} I should be able to write
fiction, poetry, opinion pieces, minor observations or collections, or anything else, and have or
create a good home for it here.}
@item{@bold{Everything produced here should look good.}}
@item{@bold{Reward exploration without disorienting the reader.} Draw connections between related
thoughts using typographic conventions and organizational devices that would be familiar to
a reader of books. Where dissimilar writings appear together, place signals that help the reader
understand what they are looking at, switch contexts, and find more if they wish.}
@item{@bold{Everything is produced, and reproducible, by an automatable process.} No clicking or
tapping around in GUI apps to publish web pages and books.}
]
@section{Names for things and how they fit together}
The Local Yarn is mostly comprised of @tech{articles} (individual writings) which may contain
@tech{notes} (addenda by the author or others) and may also be grouped into @tech{series}. These are
similar to a typical blog’s @italic{posts}, @italic{comments} and @italic{categories}, but there are
important differences.
@subsection{Articles}
The @deftech{article} is the basic unit of content, like a typical blog post. In the web edition,
each article has its own @tt{.html} file; in print editions, an article may comprise either
a chapter or a part of a chapter, depending on the content.
An article can start out very small — just a date and a few sentences. @bold{Supplying a title is
optional.} Later, it may grow in any of several directions: @tech{notes} can be added, or a title, or
cross-references to later articles; or it may be added to a series. Or it may just remain the way it
started.
@subsection{Notes}
A @deftech{note} is a comment or addendum to an @tech{article} using the @racket[note] tag. It may
be written by the same person who wrote the article, or submitted by a reader.
@(define-runtime-path diagram-notes "diagram-notes.png")
@centered{@responsive-retina-image[diagram-notes]}
As shown above, a note appears at the bottom of the article to which it is attached, but it also
appears in the blog and in the RSS feed as a separate piece of content, and is given the same visual
weight as actual articles.
A note may optionally have a @deftech{disposition} which reflects a change in attitude towards its
parent article. A disposition consists of a @italic{disposition mark} such as an asterisk or dagger,
and a past-tense verb. For example, an author may revisit an opinion piece written years earlier and
add a note describing how their opinion has changed; the tag for this note might include
@racket[#:disposition "* recanted"] as an attribute. This would cause the @tt{*} to be added to the
article’s title, and the phrase “Now considered recanted” to be added to the margin, with a link to
the note.
@subsubsection{Notes vs. blog “comments”}
Typical blog comments serve as kind of a temporary discussion spot for a few days or weeks after
a post is published. Commenting on an old post feels useless because the comment is only visible at
the bottom of its parent post, and older posts are never “bumped” back into visibility.
By contrast, notes on @italic{The Local Yarn} appear as self-contained writings at the top of the
blog and RSS feed as soon as they are published. This “resurfaces” the original article
to which they are attached. This extra visibility also makes them a good tool for the original
author to fill out or update the article. In effect, with notes, each article potentially becomes
its own miniature blog.
The flip side of this change is that what used to be the “comment section” is no longer allowed to
function as a kind of per-article chat.
@tabular[#:sep @hspace[1]
#:style 'boxed
#:row-properties '((bottom-border top))
(list
(list @bold{Typical Blog Comments} @bold{Local Yarn @emph{Notes}})
(list "Rarely used after a post has aged"
"Commonly used on posts many years old")
(list "Visible only at the bottom of the parent post"
"Included in the main stream of posts and in the RSS feed alongside actual posts")
(list "Invites any and all feedback, from small compliments to lengthy rebuttals"
"Readers invited to treat their responses as submissions to a publication.")
(list "Usually used by readers"
"Usually used by the original author")
(list "Don’t affect the original post"
"May have properties (e.g. disposition) that change the status and
presentation of the original post")
(list "Moderation (if done) is typically binary: approved or not"
"Moderation may take the form of edits and inline responses."))]
@subsection{Series}
A @deftech{series} is a grouping of @tech{articles} into a particular order under a descriptive
title. A series may present its own written content alongside the listing of its articles.
The page for a series can choose how to display its articles: chronologically, or in an arbitrary
order. It can display articles only, or a mixed listing of articles and @tech{notes}, like the blog.
And it can choose to display articles in list form, or as excerpts, or in their entirety.
A series can specify @italic{nouns} (noun phrases, really) to be applied to its articles. So, for
example, a series of forceful opinion pieces might designate its articles as @emph{naked
aspirations}; the phrase “This is a naked aspiration, part of the series @italic{My Uncensored
Thoughts}” would appear prominently in the margins. Likewise, a time-ordered series of observations
might call its articles “journal entries”.
It will be easy for any series to become a printed @emph{book}, using the techniques I
demonstrated in
@ext-link["https://thelocalyarn.com/excursus/secretary/posts/web-books.html"]{@italic{The Unbearable
Lightness of Web Pages}}, and in @other-doc['(lib "bookcover/scribblings/bookcover.scrbl")].
@subsubsection{Series vs. blog “categories”}
Typical blogs are not very good at presenting content that may vary a lot in subject, length and
style. The kind of writing I want to experiment with may change a lot from day to day, season to
season, decade to decade. I wanted a single system that could organize extremely varied kinds of
writings and present them in a thoughtful, coherent way, rather than starting a new blog every time
I wanted to try writing a different kind of thing.
My solution to this was to enrich the idea of “categories”. Rather than being simply labels that you
slap on blog posts, they would be titled collections with their own unique content and way of
presenting articles and notes. In addition, they could pass down certain properties to the posts
they contain, that can be used to give signals to the reader about what they are looking at.
@tabular[#:sep @hspace[1]
#:style 'boxed
#:row-properties '((bottom-border top))
(list
(list @bold{Typical Blog Categories/Tags} @bold{Local Yarn @emph{Series}})
(list "Every article needs to have one"
"Many or most articles won’t have one")
(list "Named with a single word"
"Named with a descriptive title")
(list "Has no content or properties of its own"
"Has its own written content, and properties such as nouns, ordering, etc.")
(list "Broad in scope, few in number"
"Narrow in scope, many in number")
(list "Selected to be relevant for use across the entire lifetime of the site"
"Selected without reference to future creative direction; may be closed after only
a few articles"))]
