Linux Server Hacks, Volume Two

Hack #38. Usable Documentation for the Inherently Lazy

Web-based documentation is great, but it's not very accessible from the command line. However, manpages can be with you always.

I know very few administrators who are big fans of creating and maintaining documentation. It's just not fun. Not only that, but there's nothing heroic about doing it. Fellow administrators aren't going to pat you on the back and congratulate you on your wicked cool documentation. What's more, it's tough to see how end users get any benefit when you document stuff that's used only by administrators, and if you're an administrator writing documentation, it's likely that everyone in your group already knows the stuff you're documenting!

Well, this is one way to look at it. However, the fact is that turnover exists, and so does growth. It's possible that new admins will come on board due to growth or turnover in your group, and they'll have to be taught about all of the customized tools, scripts, processes, procedures, and hacks that are specific to your site. This learning process is also a part of any new admin's enculturation into the group, and it should be made as easy as possible for everyone's benefit, including your own.

In my travels, I've found that the last thing system administrators want to do is write documentation. The only thing that might fall below writing documentation on their lists of things they're dying to do is writing web-based documentation. I've tried to introduce in-browser WYSIWYG ...