There are basically two camps among web developers and designers as regards documentation:

Those who believe it’s pointless, and those who document their work.

Those who do not document don’t understand it’s necessity. If you know the code, they may think, then why do you need cues as to its use? How useful are witty comments in haiku form to getting the darn job done?

How utilitarian. But, the perspective does have its merits. It speaks to knowing your job, knowing your tools and, above all, doing comprehensive and elegant work.

On the other hand, you have the developers and designers who love to document. This ranges from simple cases such as building a readme.txt for every module they build – all the way up to those who create ascii art from their functional notes. It’s fairly varied, because there are no real conventions for software documentation, especially in open source.

And it’s not just in software. Right down to html structure in websites and override hierarchies in CSS files – documentation can be more than just thorough, it can also be elegant.

Documentation may seem frivolous to some, but the point is clear: you need to know where you’ve been to know where you’re going. What happens to your elegant programming if you disappear, or if someone else takes it over? Good documentation can prevent backward engineering, as well as allowing for more efficient forking, revisioning, and repetitive versioning.

By and large, I’ve seen graphic designers like documentation less than functional or application developers. The group I’m seeing lean toward documentation more and more, however, are user experience designers. People building user interfaces, designing the workflows for web sites and applications.

There are benefits to both theories – good documentation can be as helpful as elegant, minimalist code structure. However, as with so many other ventures, coding with future versions in mind is never a bad idea.

Photo by Syntopia.