Todd Wolfson

Software Engineer

September 13, 2016

Resumable work is code that is sufficiently documented, commented, and straight-forward that you and others can understand the author's intentions, continue work, and extrapolate future solutions.

With my recent return from Berlin to return to my work (see Medium), I was reminded by how proper preparation can make or break a project.

My first encounter with resumable work was playing Harvest Moon in my childhood; I would take 6 month breaks and be fully disoriented when I returned. I tried writing pages of notes to my future self but it never work and only added to my aggravation.

When I started doing open source, I recognized the same problem immediately. I would return to a repo I wrote and have no context. After enough trial and error, here's what I found worked:

  • Workflow oriented documentation (e.g. how to get started, which scripts do what, how to use them)
    • See twolfson.com-scripts as an example
    • Self-documenting repositories are great for APIs but not amazing on concepts for developers
    • We need to be empathetic to how someone is using our repo which is a different mindset than we use while writing code
  • Well commented repositories
    • Even in languages like Python, not all intentions are obvious
    • Currently I use 2 comment variations: normal ones documenting the intent of code (e.g. look up users by their id) and DEV: comments for implementation reasons (e.g. we use mkdir with -p to avoid "File exists" issues)
  • Automated testing
    • Manual or light testing can work for early stages of development but edge cases can easily be forgotten
    • If manual tests are required (e.g. verifying CLI options), then document them as part of the testing documentation

In the scope of larger work (e.g. multi-repo projects):

  • Project planning
    • Short term planning (i.e. next few weeks) and granular down to 1 day tasks
    • Long term planning (i.e. next few months) should be vague and broad topics/goals
    • Anything that's a nice idea should be thrown into a backlog but not left on short term planning (this avoids overwhelming new/returning developers)

Top articles

Develop faster

Removing the tedium from creating, developing, and publishing repos.

Sexy bash prompt

A bash prompt with colors, git statuses, and git branches.

Recent articles

Parallel visual testing

Comparison of parallelization techniques for visual testing