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.

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}

We can say build.sh runs something like this to make a PDF of a story.

pdflatex -halt-on-error    \
-output-directory \
./dist ./story/aggregate.tex

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 processed by code. We’ll see why in a moment.

The Branches Make It

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

• The master branch holds a project that compiles to PDF and tells a complete story.
• An elaborate (develop) branch adds detail to the story.
• A concept (feature) branch introduces at least one unique, self-contained concept in concept/ later used to elaborate.
• A review (release) branch holds a complete story for review. If the story is of sufficient editorial quality it may merge to master.
• A reconcile (hotfix) branch fixes pressing logical errors such as plotholes.
• A seed (support) branch addresses circumstantial concerns such as differences in story arcs or fictional universes.

To enable the Snowflake Method, master should hold a complete story, but that story does not have to be publishable. The project will face a “soft end” on a commit to master representing a publishable story. Different universes, story arcs, or derivative products follow.

So what’s the point?

The workflow builds several products at once.

concepts/ eventually takes the shape of “behind the scenes” content that can separately packaged and sold. So long as commits are disciplined, the commit history cleanly deliniates what got accepted and what got left behind. Letting concepts/ sit as a process-free sandbox within an otherwise regimented workflow just adds color to the mix.

The git-flow branches also create analogous workflows for creative writing that makes a lot of sense to me.

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

• Elaborate on all relevant footnotes.
• git flow release start ...
• Compile a PDF to release to trusted readers for feedback.
• From the feedback, insert a list of footnotes (or other annotations) where applicable according to your own best judgement.
• Address all footnotes.
• Repeat steps 3–6 until there exist no footnotes.
• 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.

• Do not adjust the story/ to the concepts/, adjust the concepts/ to the story/.
• Do not modify story/ when on a concept branch.
• Your comfort and focus on writing comes before the process. Don’t be afraid of relaxing with pen and paper to decide what to do. Lay down on the floor and sketch on a bunch of Post-Its next to a cup of tea before typing anything.

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.