Minimalist Online Docmentation

Motivation and history

Anyone who has worked as a system administrator, and especially with a team of other system administrators, knows that good documentation from your present and past coworkers can make your work much more efficient and enjoyable. For some time I've been trying to design a documentation system that would encourage good note-taking and documentation skills. It should be simple enough that someone working on a problem won't hesitate to open a file and jot down some thoughts, but it should still offer enough power to illustrate complex ideas when necessary and encourage good organization and presentation so that it results in a functional, usable product.

MOD is my attempt to design a system that aspires to meet these goals. Earlier attempts never quite struck this balance well enough to get off the ground, but MOD feels at least a little closer.

Development of MOD itself began in December 2000 at Penn State's Environment Institute where I worked as a system administrator, and to whom I'm very grateful for providing the time and resources for MOD's development.

In September 2002, after MOD had been in use for almost two years, it was released under the terms and conditions of the GNU GPL so that it could be more widely used, and its development could continue.

Alternatives

When I was looking for a tool to meet my needs (still not intending to write it myself), I came across quite a few packages that came close, but never quite met all of the criteria I had in mind for this particular purpose. Some packages lacked only simplicity. Some of these alternatives may turn out to be exactly the right solution for you, though, if MOD doesn't quite suit your needs:

• POD: More designed for individual man pages, I really liked the simplicity of the tag syntax (obviously), but it was too difficult to include free-form hyperlinks, and there wasn't any real support for an indexed document hierarchy.

• Simple Documentation Format: This one was painfully close to what I wanted, but once I started working with it, I got the impression that it had so many features that it was no longer simple. I felt that its learning curve was too great to be universally accepted by everyone I was working with. If nobody feels like spending the time to learn a new format, it doesn't matter how good it is, since nothing gets written.

• Almost Free Text, in my opinion, has a fabulous means of representing internal document structure, better than MOD's. The only problem is that it's designed more for single documents, rather than indexing and organizing an entire web site with a consistent layout.

• HTML & CSS: All of the power and consistency tools, but unfortunately the learning curve is a bit too steep to convince everyone to use it. Also, I would really miss the auto-indexing.