@@ -2,40 +2,156 @@ @; 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{Design Background} +@title{Basic Notions} + +@section[#:tag "design-goals"]{Design Goals} -The design and implementation of @italic{The Local Yarn} are 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. +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{Everything produced here, both in print and on the web, should look good.} - @item{@bold{All the output should be produced (and reproducible) by automated processes.} No - clicking on buttons in apps to publish web pages or books.} -] - -@nested[#:style 'inset]{ - “Yet modest ornament with use combined @(linebreak) - Attracts the eye to exercise the mind.” @(linebreak) - —@ext-link["https://en.wikipedia.org/wiki/Samuel_Rogers"]{Samuel Rogers} -} + @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{Experimentation must be accomodated gracefully.} 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. Where dissimilar writings appear together, there should be signals that + help the reader understand what they are looking at, switch contexts, and find more if they wish.} + + @item{@bold{Everything produced here should look good.}} + + @item{@bold{Reward exploration without disorienting the reader.}} + + @item{@bold{Everything produced here should be the result of an automatable process.} No clicking + around 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. 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. + +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 heading. +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 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} to be applied to its articles. + +@subsubsection{Series vs. blog “categories”} + +Typical blogs are not very good at presenting content that may vary a lot in 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 and present it all, 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" + "Name with a descriptive title") + (list "Has no content or properties of its own" + "Has its own content and properties") + (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"))] +