cd ~

Creative writing with git-flow and the Snowflake Method

git-flow’s value depends on the nature of a project. Take creative writing: Randy Ingermanson’s Snowflake Method makes you start from a crude—yet complete—one-sentence story and iterate until you are left with a good story. Requirements imposed by The Snowflake Method are analogous to git-flow’s role for the master branch. Given a LaTeX project managed with a combination of git-flow and the Snowflake Method (“Snowflow”), we get some interesting properties.

Assume this file system:

build.sh          # Compile PDF(s) in dist using story/
dist/             # .pdf files
concepts/         # whatever
story/            # .tex files
    aggregate.tex # \document{book}

At minimum build.sh runs something like pdflatex -halt-on-error -output-directory ./dist ./story/aggregate.tex to make a PDF of your story. The concepts/ directory contains assets describing characters, settings, conflicts and plot decisions. One rule for this project is that the concepts/ directory be checked in, but _never be processed by code._ This allows free-form creativity in asset production that a precise process would otherwise curtail.

Snowflow branches behave analogously to their git-flow counterparts, with some added expectations.

To enable the Snowflake Method, master should a complete story, but that story does not have to be publishable. On that note an early iteration for Therac–25’s firmware shouldn’t have seen the light of day. It may seem insensitive to compare death by radiation overdose to bad writing, but only if you’ve never read anything by Dan Sacharow.

A Snowflow project will face a “soft end” on a commit to master representing a publishable story. Unless you come up with different universes, story arcs or derivative products there may be no need to measure progression or compatibility with version numbers or tags.

In experimenting with this workflow my favorite discovery is that concepts/ eventually takes the shape of “behind the scenes” content for readers, which may be separately packaged and sold. So long as commits are disciplined, the commit history helps you build several products at once, where the main story you intend to publish implicitly promotes content you could produce using information in concepts/.

The concepts/ directory also serves as a sandbox for inspired writing sessions. Writing is pretty moody. Sometimes I feel disciplined and can see how to package my commits, and other times I just want to write with no distractions. So if you want to hammer out a few thousand words in a text file in concepts/, go nuts. You can always worry about structuring the content with Snowflow when you are ready.

Elaboration process

I must elaborate on the elaborate branch. elaborate may either expand on the story or perform technical tasks using LaTeX. In the former scenario, I use footnotes containing at least one question or instruction to identify opportunities to build on the story.

You don’t have to use footnotes, but keep in mind that someone who reviews your work should not have to be a developer. I like having something visible in the product for an author and editor to discuss.

For example:

Bob jumped over Alice. \footnote{But WHY did Bob jump over Alice?}

To make the elaboration process sensible, you should write content that addresses a footnote either in the vicinity of where the footnote appeared, or in a location that better establishes context. When you resolve the matter raised by a footnote, remove that footnote.

When you commit to an elaborate branch you may add at least zero footnotes, but you must remove at least one of the footnotes found when you started. By the time you start a review branch there should not exist any footnotes.

Review process

  1. Elaborate on all relevant footnotes.
  2. git flow release start ...
  3. Compile a PDF to release to trusted readers for feedback.
  4. From the feedback, insert a list of footnotes (or other annotations) where applicable according to your own best judgement.
  5. Address all footnotes.
  6. Repeat steps 3–6 until there exist no footnotes.
  7. git flow release finish

Guidelines

Writing can’t be constrained by too many rules, but I did note these guidelines and observations down as I worked.

Licensing Snowflake Method content

If you decide to write using this process, stay mindful of where you publish your working code. If your product is a book, license it like a book. But more than anything, consult someone qualified to talk about licensing. Of course some books like You Don’t Know JS are open source, but if you are concerned about distribution, do your research and choose a license.