read


read or learn more

Marginalia has a new home.

Aug 12, 2013

A few days ago I posted that I was looking for a new home for Marginalia and today I am happy to say that I have found one. Gary Deer has graciously agreed to take the reins and push Marginalia in new and exciting directions. Two projects fall under the Marginalia banner: Marginalia https://www.github.com/gdeer81/marginalia lein-marginalia […]

Marginalia needs a home

Aug 7, 2013

A long time ago I wrote a blog post entitled The Marginalia Manifesto that described my motivations for developing the Marginalia documentation system. While much of what I wrote about documentation still holds in my own mind, I have long since become a mere user of my own software. That is, what Marginalia does right […]

Documentationation

Jan 22, 2013

Code documentation is like raising kids; you can’t just bring a document into the world and hope it’ll fend for itself. The art of writing documentation and documentation tools is an ongoing learning, modification and improvement process. Sadly, I have been somewhat lax in the past year tending my documentation babies. This post is my […]

This PLT Life: Self-documenting code

Jul 6, 2012 some comments

Inspired1 by Manuel Simoni’s This PLT Life series I present, “When someone tells me they’ve written self-documenting code”: :F Stolen ↩

The Marginalia Manifesto

Jan 5, 2011 some comments

I have a very strong opinion regarding the importance of clear and complete documentation. My reaction to poorly documented code, products, and services is visceral to the point where I often refuse to release even the most humble library without code comments, examples, tests, invariant definitions, a logo, and an “official website”. However, time is not always on my side for my personal projects, so I am constantly looking for ways to minimize the amount of work required to generate well-documented software without sacrificing quality. Marginalia is a step in that direction.

Continue