workings-book/entries/2015-01-28.md

<h1>Wednesday, January 28</h1>

on replicating process
----------------------

Ok, so here we are.  It's 2015.  The gold standard for explaining how you
solved a technical problem to the internet at large is a blog post with things
you can copy and paste or maybe some pictures.

If you're really lucky, someone actually has reusable a public repository of
some kind.  If you're _really_ lucky, their code works, and if all the gods
are smiling on you at once, their code is _documented_.

It seems to me that we can do better than this.  We possess a great many of the
right _tools_ to do better than this, at least for a lot of common problems.
What does it take to make a given workflow both repeatable and legible to
people without the context we have for a given thing (including ourselves)?
Writing about it is surely desirable, but how do you approach a problem so
that, instead of being scattered across your short term memory and a dozen
volatile buffers, your work becomes a kind of document unto itself?

This is the (beautiful) root of what version control does, after all:  It
renders a normally-invisible process legible, and in its newfound legibility,
at least a little susceptible to transmission and reuse.

What do I know works well for transmitting process and discovery, as far as it
goes?

- version control (so really git, which is severally horrible but also
  brilliant and wins anyway)
- Makefiles (except that I don't understand make at _all_)
- shell scripts (except that shell programming is an utter nightmare)
- Debian packages (which are more or less compounded of the above, and
  moderately torturous to build)
- IRC, if you keep logs, because it's amazing how much knowledge is most purely
  conveyed in the medium of internet chat
- Stackoverflow & friends (I hate this, but there it is, it's a fact, we have to
  deal with it no matter how much we hate process jockies, just like Wikipedia)
- screenshots and screencasts (a pain to make, all-too-often free of context, and
  yet)

Here are some things that I think are often terrible at this stuff despite
their ubiquity:

- mailing lists (so bad, so _routinely pathological_, so utterly necessary to
  everything)
- web forums like phpBB and stuff (so bad, so ubiquitous, so going to show up
  in your google results with the hint you desperately needed, but only if you're
  smart enough to parse it out of the spew)

Here's one problem:  There are a lot of relatively painless once you know them
tools, like "let's just make this a dvcs repo because it's basically free",
that if you know they exist and you really want to avoid future suffering you
just get in the habit of using by default.  But most people don't know these
tools exist, or that they're _generally applicable tools_ and not just
specialist things you might use for the one important thing at your job because
somebody said you should.

what makes programming hard?
----------------------------

0. Most of the existing programs.
1. Most of the existing programming languages.
2. Other programmers.
3. Human thought is brutally constrained in understanding complex systems.
4. Ok you wrote some programs anyway now GOTO 0.

debian packaging again
----------------------

I'm starting [here](https://www.debian.org/doc/manuals/maint-guide/) again.

- https://wiki.debian.org/IntroDebianPackaging
- https://www.debian.org/doc/manuals/packaging-tutorial/packaging-tutorial.en.pdf
  (actually more helpful than anything else I've found so far)

vagrant
-------

Vagrant is a thing for quickly provisioning / tearing down / connecting to
virtual machines.  It wraps VirtualBox, among other providers.  I think the
basic appeal is that you get cheap, more-or-less disposable environments with a
couple of commands, and there's scaffolding for simple scripts to configure a
box when it's brought up, or share directories with the host filesystem.  It's
really lightweight to try out.

Go to the [downloads page](http://www.vagrantup.com/downloads) and install from
there.  I used the 64 bit Ubuntu .deb.

    $ sudo apt-get install virtualbox
    $ sudo dpkg -i vagrant_1.7.2_x86_64.deb
    $ mkdir vagrant_test
    $ cd vagrant_test
    $ vagrant init hashicorp/precise32
    $ vagrant up
    $ vagrant ssh

This stuff takes a while on the first run through, but is generally really
slick.  `hashicorp/precise32` is more or less just a preconfigured image pulled
from a central repository.

Their [Getting Started](http://docs.vagrantup.com/v2/getting-started/index.html) is pretty
decent.

People around me have been enthusing about this kind of thing for ages, but I
haven't really gotten around to figuring out why I should care until recently.
I will probably be using this tool for a lot of development tasks.

Other notes:

* stackoverflow: [How can I create a VM in vagrant with virtualbox with two cpus?](https://stackoverflow.com/questions/17117063/how-can-i-create-a-vm-in-vagrant-with-virtualbox-with-two-cpus)
* [Development Environments with Vagrant, Docker, and Supervisord](https://tylercipriani.com/2014/05/25/lightweight-portable-vagrant-docker.html)