Apparently, there is a setting in OpenSSH 5.1 and later for visual remote host fingerprinting.  The basic concept is that it’s much easier for the human brain to notice a change in a visual pattern than in a string of hex digits.  To turn it on, simply add a line that says
VisualHostKey yes to your ~/.ssh/config file. Then, when you go to SSH into a server, you’ll see a visual representation of the remote host fingerprint, in addition to the regular fingerprint, as shown below:

[jsmith@hockey ~]$ ssh fedorapeople.org
Host key fingerprint is 07:d4:02:db:9f:70:d5:2d:7f:1b:6a:df:83:73:95:1d
+--[ RSA 2048]----+
|      ....  .. . |
|       +. ..  o .|
|      . +..    o |
|         = .   Eo|
|        S +   . B|
|         .   o oo|
|            . o o|
|             o +.|
|              o .|
+-----------------+

See, now isn’t that handy?

In trying to actually use the remote control, however, I was given a stark reminder of how important documentation can be.  As you probably already know, I try to take an active role in the documentation teams for both Asterisk and the Fedora Project, but never seem to make the time to write as much as I’d like.  As such, I can only hope our documentation efforts are more effective than the yellow labels on my remote control — just documenting the bare minimum and forcing the user to experiment to do anything useful (and very likely getting lost in the process).

(It’s my own personal opinion that this is one of the ways that free/open source software often fails to keep up with it’s commercial rivals; Many open source projects can’t afford to hire technical writers, and if they’re lucky enough to have volunteers do the work, there often isn’t much praise for the hard work and effort that goes into it.)

If this reminder has you feeling the same way I am, why not step up to the plate and help out on the documentation front?  After all, the fearless leader and the rest of the docs crew needs your help!  As the old adage goes… many hands makes light work!  We’d be glad to have you join our ranks.

So, to make a short story long, I do a lot of writing. (Much more than I’d honestly like, but people tell me they like my writing style — go figure.) I do most of my technical writing using the DocBook format. If you’re new to DocBook, I suggest you take ten minutes, read this article written by the intrepid Paul W. Frields. It’ll give you the background you need on what DocBook is and how it works. Then come back and finish this article. (You’ll thank me later.) And to answer your questions: Yes, I actually take the time to write out all those XML tags. By hand. In vim. Yes, I actually write books in vim. Go figure.

So one of the toughest parts of getting started in DocBook (like most IT-related projects) is setting up the infrastructure. This is where Publican comes along… it takes care of all that for you. It builds you a skeleton that you can then flesh out, and takes care of all the things you’d rather not have to worry about, like packaging, translation, and building various versions of the output (say in HTML, chunked HTML, and PDF versions). I probably spent at least a good twenty or thirty hours (or more) setting up the infrastructure for the last DocBook project I started… mostly setting up files (and the various links between them), tweaking the Makefiles, etc. It was not exactly my definition of the word “fun”.

So on a whim last night, I figured I’d start checking out Publican and see how long it would take. In less than 15 minutes, I had Publican installed and an existing DocBook document ported over to it (the new revision of the Software Management Guide, as part of the Fedora Documentation Project). You can see the HTML output of my endeavor here, complete with Fedora branding and everything. Now I don’t know that Publican is going to be a perfect fit, especially given some of the unique requirements of the Fedora Documentation Project, but I have to hand it to Jeff Fearn and the others on the Red Hat documentation team — they’ve created a lean mean doc-building machine! I tip my hat to you!

If you’re already running rawhide, you should be able to simply install the “publican” and “publican-fedora” packages. If you’re running Fedora 8, you can simply point to Bob Jensen’s personal docs repo and install the packages from there.