- I keep all my notes in markdown format. Usually this is configuration data on systems or networking equipment.

- In addition to plain text, using a text snippets engine I have data embedded in the notes document so that they are also machine readable/parseable.

- Using this, I can dump everything through pandoc or similar to generate nice looking hardcopy, or through a script that could “pull all IP/DNS A-record pairs out, test that DNS works correctly forward and reverse, then ping all the IP’s to verify that the hosts are up”, or “use this to write out a configuration file for daemon X”.

- The documentation (at least the parts that are machine intelligible) is therefore able to be tested.

This doesn’t solve the culture issue, but it does solve one part of the accuracy issue, and avoids some of the the downsides of Wikis (ex: http://utcc.utoronto.ca/~cks/space/blog/web/WikiTrap )

http://www.hollenback.net/index.php/SendMimeWithPerl

P.

1. Perl is installed on most systems (although the MIME::Lite module probably isn’t be default so you would need to grab it from cpan).

2. This automatically handles niceties like the content-disposition string and base64 encoding so you don’t have to worry about them.

Here’s a minimal script that takes stdin and sends it as a text attachment:

#!/usr/bin/perl -w

use MIME::Lite;

# create a new mime message
$msg = MIME::Lite->new(
To => $ARGV[0],
Subject => $ARGV[1],
Type => ‘multipart/mixed’
);

# add stdin as a text attachment
$msg->attach(
Type =>’TEXT’,
FH => STDIN
);

# send the message.
$msg->send;

usage:

cat blah | mmail.pl user@example.com “here’s my stuff”

I tested that out and it produces the desired results.

./kj