I wanted to take just a short time out to discuss (read: rant) something that is near and dear to my heart.


It seems simple, and most importantly seems obvious, but it’s too frequent I see formatting faux-pas all over the place. My most recent experience was having to dive into an AS2 project, only to realize it’s been six (wow SIX?!?! ALREADY!?!) years since my short stint of AS2 development. So what’s a developer to do? Ah yes, consult the documentation.

I present to you Evidence A… OK, I’m not going to point fingers in a static format (if you follow me on FB or Twitter, I’ve already publicly done this) but when you have a platform that is so ubiquitous, you’d think your documentation would be primo. Not in this case; I come to the topic at hand only to find that looking at the page made my eyes bleed and pluck themselves out of my skull. OK, hyperbole in hand, I decide to continue looking at said documentation, and while I can appropriate the information I need, it’s like trying to look at one of those 3D illusion paintings that you have to tilt your head, squint your eyes, and make up things until the person next to you says “close! but it’s a boat.”

To me formatting can make or break anything from documentation to source code, to even every day things like a newspaper article or a blog posting (I hope I’m doing ok here).

I’m not going to cover any REAL standards here, but it is necessary to point out that depending on what outlet medium you choose (formal paper, documentation, source code, advertisements, etc) there is most likely a standard for the formatting methodology that you NEED to follow. Don’t be foolish, we know formatting does NOTHING for you since you’re the one writing it – but think of those that will stumble across your work and have a feeling of immense loss and confusion only because of your inability to format your information properly.

A while back, my wife and I were looking at the proper way to install siding on our custom built shed, and while the information IS out there, but it’s SO hard to find anything worthwhile. I present Evidence B. Once you’ve wiped your eyes of the pools of blood, I want to be very courteous and state that this site actually had the most pertinent information, but presented in such a way that made it extremely difficult to follow. To impress my frustration, I literally read the entire site top to bottom no less than 8 times, each time having to copy/paste data into notepad to organize it better for myself. If it was formatted properly, I most likely would have only had to have read it once, and refer to it occasionally for quick referencing.

So, boys and girls, keep in mind that if you’re going to bother putting information out there you need realize that not everyone thinks like you do; so a stream of consciousness is a poor way to present anything worthwhile.

OK, time to get back to this source code, which is luckily formatted VERY well.