Whether you’re a high-school or University graduate, there’s one thing our mentors have tried to impregnate into our brains as a vital tool to comprehend and memorise the information we are taking in; making notes of what we read, see, and hear. Granted, to some it may seem redundant or far too time-consuming to engage in exhaustive documentation of one’s reading and learning material. And there are indeed areas of learning where you don’t need it.

If I do it with Books, why not do it with Websites?

What do your books look like? Are they neat and clean? I don’t mean coffee marks or other unnescessary stains or speckles of dirt; I mean clear signs that a book is heavily used. My books mdash; for the most part mdash; are a complete mess. Why? Because they’re tools. They’re the hammer and chisel I use, sometimes abuse, excessively amd exhaustively. I write extensive notes on the sides of a page, sometimes a hundred words or more. I underline paragraphs, add questions or exclamation marks when I feel something is either right on the mark or when I’m uncertain of the meaning of certain paragraphs. I use a yellow neon-marker to mark passages that contain a thesis, mark passages in neon-pink that illustrate possible anti-thesis/counter-arguments, and finally use a green marker to highlight the thesis’ conclusion. I place paper notes where adequate with bullet points to help me find the proper information I seek next time I need it. In short, my books look used, torn, and often have very little resemblance in apperance to when I originally bought them.

On the web, having a documentation habitus, is of even greater importance, unless you design solely for yourself.

Only recently, I’ve made it a habit to always document significant steps taken during the course of designing a web site for a client. While doing this may be considered a daunting and unnerving task, it can pay off in the end, and in more ways than one.

The Benefits are not Limited to the Designer

Firstly, I tend to experiment a lot when constructing and prototyping a new design. This is not only a fun task, but also a very challenging one many times. Designing layouts that contain stylistic touches that are not overly common, usually require for my CSS to be extravagant as well. There is no way at all, I will remember what I did to client x’s design four years ago. Not remembering means lots of searching and guesswork. Lots of searching means lots of time wasted. I can’t tell you how many times I’ve had to revisit my own techniques because I had failed to document exactly why and how I coded something, relying on my memory entirely, which is not a very wise thing to do.

Secondly, documenting code and explaining why I have written a piece of code in such way or another, also tells me that I understand exactly what I’m doing. If I don’t know the whys and hows, or have quickly looked up a technique from a book without having learned the methods applied thoroughly, I won’t be able to explain it, right? Right.Therefore, documenting properly can be a good mirror to my current level of expertise.

Thirdly, the most important benefit to documenting my code is to enable clients and developers to maintain the site independently from me, should they so choose, and doing it beautifully, without breaking the design, its aesthetics, and its accessible markup.

Well-documented Code is more than a Memory Crutch

What it really is, is a:

  • Accessibility Enabler - I am able to explain why I used non-semantic containers such as the span element, and slightly more semantic mdash; but still fairly neutral mdash; such as the div element to construct my contact form instead of using a list or table.Because opinions on Best Practices in the Web Standards world differ quite significantly in many areas, having good arguments for doing what I do and being able to explain why I chose what I chose, allows for insight, discussion, and enhancements. I can replace certain elements based on newly won cognition on how to best present specific information.
  • Usability Enforcer - When having performed a re-design for Jane Doe’s company, I’ll have documented why I’ve done away with the poorly executed drop-down menu and instead applied a one-level navigation, and placed sub-menu items on the right-hand side. Shall a designer/developer mdash; at any given time mdash; seek to make changes to the navigation architecture, he’ll know and understand the reasoning behind my design decision.
  • Efficiency Maker - Obviously, having documented my code will help save time. I can come back to a design I’ve made years ago and can quickly access the information and logic of the code applied. I may just want to modify the colour scheme slightly. Perhaps I’d like to reduce the markup significantly, optimize, or enhance it to accomodate new browser-integrated CSS rules and the like. I can do this easily when I have my style-, and HTML documents well commented. It not only saves me a lot of time and headaches, and the client lots of money, but is simultaneously most beneficial to developers or teams who work on and maintain the same site.

So, making notes, writing good documentation is not a waste of time, not in the long run. I wish I had started out this way when creating websites and using the space I’m given in a HTML or style document, and mdash; for extensive documentation mdash; use separate documents to write down a table of contents, just like any good book does.