Day 7: Prototype (Mise en place)

I have a tendency to do the bare minimum needed at the beginning of a project. If I subsequently forget things or start from no structure at all, it leads to spending a bunch of time tidying up and moving files around later on.

Conversely, if I start with files and directories created from generic template repos or boilerplate automation, it can feel depersonalised and crufty, like I’m hacking on someone else’s project where not everything is relevant.

Mise en place is an analogy from cooking or running a kitchen which is very relevant to software development and many other creative activities.

this, I’m going to write a one-off initialisation script that sets everything up the way I want it. This might take a fraction more time than writing it by hand or copy-pasting from different sources. The benefit for me is that it provides a constraint around reviewing decisions about how to structure things.

First, create the directory and initialize a Git repo.

mkdir ~/Projects/exoplanetariad
git init ~/Projects/exoplanetariad

Next, create an empty Rakefile.

touch Rakefile

Then, the initialisation script. This is where I do my initial thinking about structure and requirements. Beyond the elements of a conventional Ruby project, this also needs to support book production for print and screen.

• Design research, notes and exemplars. This is something I incorporate in many of my projects. It may be less relevant in this particular context as I’m working through a lot of that process writing these notes.
• Font assets for embedding in PDFs. Open Source licensed fonts can be added to the repo. Fonts I’ve purchased that I don’t have a license to share should be ignored.
• Front matter, colophon and other fixed text elements that make up the structure of a book. Not all of this needs to come from generated text. After creating various iterations of generated books over the years, the pattern I’ve settled on is to mark up each element in a separate plain text file.
• Corpora, word lists, images and data. Not all my generated books build on a foundation of raw source material but it’s useful to plan for it explicitly.
• Temporary files and logs. These projects often end up with huge volumes of generated data, intermediate result files and debug logs. Should be ignored.
• Final generated output documents for print and screen. These may or may not be added to the repo.

GITIGNORE = [
  "drafts/",
  ".DS_Store"
].join("\n")

GEMFILE = [
  "source 'https://rubygems.org'",
  "gem 'calyx'",
  "gem 'prawn'"
].join("\n")

task :init do
  mkdir "lib"
  mkdir "spec"
  mkdir "drafts"
  mkdir "fonts"
  File.write ".gitignore", GITIGNORE
  File.write "Gemfile", GEMFILE
end

Run it and install the Gem dependencies using Bundler.

rake init
bundle