Ian M Rountree

Copywriter, Project Manager, Digital Marketing

  • Copywriting
    • Content Marketing
    • SEO
  • About
  • Contact

A Note About Documentation

June 20, 2010 by Ian 2 Comments

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.

Filed Under: Blog Tagged With: code, design, user experience, ux design, web design, web development

Categories

  • Announcements
    • Event Notices
  • Blog
  • Communication
  • Content Strategy
  • Marketing Strategy
  • Personal
  • Reviews
  • Social Media
  • Technology

Archive

  • January 2016
  • June 2015
  • October 2014
  • September 2014
  • January 2012
  • December 2011
  • November 2011
  • September 2011
  • August 2011
  • July 2011
  • June 2011
  • May 2011
  • April 2011
  • March 2011
  • February 2011
  • January 2011
  • December 2010
  • November 2010
  • October 2010
  • September 2010
  • August 2010
  • July 2010
  • June 2010
  • May 2010
  • April 2010
  • March 2010
  • February 2010
  • January 2010
  • December 2009
  • November 2009
  • October 2009
  • September 2009
  • August 2009
  • July 2009
  • June 2009
  • May 2009
  • April 2009
  • March 2009
  • November 2008
  • October 2008
  • July 2008
  • February 2004
  • Copywriting
  • Blog
  • Reading Lists
  • Colophon

© Copyright 2023 Ian M Rountree · All Rights Reserved