Using dot from graphviz

The whole graphviz package is an amazingly useful piece of software.  Especially the dot program.

I've watched other people hand-craft Visio documents that go out of date really fast.

I've also watched developers try to use design tools for high-level sketch kind of diagrams and get bogged down with superfluous code-sync features.

When I want to illustrate a point, just plain old boxes and arrows work wonders.  Especially when I can commit the source and be able to tweak it afterwards.

I've found that dot meets and exceeds the my common use goals.  I would guess that 80% of the time, the diagram communicates what I want to say without any tweaking at all.  About 15% of the time, it takes some layout/shape/font/color tweaking to get the message across in a clear & direct manner.  About 5% of the time, I have to output the graph as SVG and load it into Inkscape for further slight tweaking.

Here are some especially helpful links:

• official site
• gallery of examples, also 
• up-to-date language reference, and other documentation
• outdated, but very well-organized Users Guide
• dot-functions.sh

The last piece of software is intended as a helper for invoking dot quickly from the command line as part of a REPL authoring flow.

To use dot-functions.sh, first download it.  The script defines a bash function that can be used from a bash CLI.  Source it into the current shell by doing: source dot-functions.sh, followed by dot somefile.dot.


Here is the source of dot-functions.sh:

	#!/bin/bash
	echo $0 | grep -q "dot-functions.sh" && {
	echo "usage: source dot-functions.sh, then run 'dot foo.dot' and the PNG will show"
	exit 1
	}
	produce_image_type() {
	for arg in "$@"; do
	[[ "$arg" =~ -T[-_a-z]+ ]] && echo ${arg#-T} && return 0
	done
	echo "png"
	}
	dot() {
	local DOT_CMD=`which dot`
	local IMAGE_TYPE=`produce_image_type "$@"`
	for f in "$@"; do
	[[ "$f" =~ -T[-_a-z]+ ]] && continue
	# strip trailing ".dot"
	# NOTE: also handle trailing ".", which is what happens when you
	# tab-complete after the png already exists
	EXT=`echo $f | grep -o '[^.]*$'` # usually just "dot", but some people call dot files .gv
	FILE=`echo $f | sed -e 's/\.[^.]*$//' -e 's/\.$//'`
	$DOT_CMD -T$IMAGE_TYPE "$FILE.$EXT" > "$FILE.$EXT.$IMAGE_TYPE" && local IMAGE_FILES="$IMAGE_FILES \"$FILE.$EXT.$IMAGE_TYPE\"" || return 1
	done &&
	if [[ `uname -a` =~ "Darwin" ]]
	then
	eval "open $IMAGE_FILES"
	else
	eval "gnome-open $IMAGE_FILES"
	fi
	}

view raw dot-functions.sh hosted with ❤ by GitHub

Another very helpful article was written on this topic by Diomidis Spinellis.  Now that I think about it, there is another very helpful article about how to get a hand-written sketch into digital form.

Keeping a Beginner's Mind

As an experienced software developer, I care deeply about retaining my ability to remain flexible in my habits and learning style.  That's the only way I got good, and if I ossify in my learning habits, I'll end up the equivalent of a COBOL programmer.  Certainly not the way to live up to the broad possibilities that exist to make the world a better place.

I appreciated the wider perspective that I got from glancing through these slides by Patrick Kua:

The Beginner's Mind

Although I had seen and skimmed Pragmatic Thinking & Learning, this presentation was a gentle and useful introduction to the whole idea of the Dreyfus model of skill aquisition.

Another very useful idea that this presentation expressed was the contrast between "skill-acquiring apprentice" vs. "closed-minded expert".  Patrick said that the "skill-acquiring" attribute can also apply to highly-skilled practitioners.

Among the tips Patrick gave, the following were useful to me:

• You can't be an expert on everything. [so don't even try]
• How can I try this safely?
• How does this fit in my world?
• Remain curious.
• Mix with diverse groups.
• Beware of built-in biases.
• Avoid judging early.

The reason I decided to compare/contrast some of the ideas in this presentation was actually because of my forays into the Pragmatic Thinking & Learning book, which was one of three "Further Resources" offered at the end.

Patrick recommended the following books for further learning:

• Pragmatic Thinking & Learning
• Apprenticeship Patterns
• Changing Software Development

Because of the context in which the Apprenticeship Patterns book appears, I want to read that as a next step for learning how to make a real difference at FamilySearch.

Any reason not to post this?

I remember reading Tim Bray's first post at Google, specifically the part that talked about continuing to post without editorial comments from his employer.

It was then that the whole Cluetrain Manifesto finally clicked for me.

And I realized that the real question wasn't:

Would this topic be something I could post on my blog?

but was really a quick:

 Any reason not to post this? (right before hitting the Publish button)

 Seems like I've been kind of dense about this sort of thing.