glennweb.net

“Content won’t magically appear. Most “Web designers” can’t create it for you. It’s important, usually should be priority #1 on a Web project. It takes work, lots of work. It needs a plan, and a process. In many cases creating, editing and managing the content for a Web site of any size is a full time job. For a real person. A content management system won’t do anything on it’s own, and you’re better of not wasting your money if you can’t properly implement it.”

Great article from D. Keith Robinson (Asterisk) about the importance of content to a web project. Your web site can be considered a “content vehicle” (think brochure, billboard, article, etc.) with unique capabilities (incredibly timely, easily updated, free distribution, etc.). What good is a billboard without a message?

A Rant (Mostly) About Web Content

Eris | Standards in Design. Standards in Life

Eris | Standards in Design. Standards in Life

I find that, in general, much of the PHP scripts/class code (this includes Pear code) that developers make available is overly complex, requiring a large time investment to actually make it useful. Which of course actually makes their code generally less useful in real world contexts. Oh Dave, your such a critic. “What should these developers do” you say?

If you have a complex set of scripts/classes/etc. here are the things I would want to help my ‘real world ramp-up time’ with your code:

• A High-Level Diagram: nothing elaborate, but I want to see from a higher level how your code fits in with its surroundings (PHP, databases, directories, servers, etc.). If your documents dump me right in at the branches-on-trees levels it will take me days of dinking with it to see the actual forest, days I spend in frustration (why the heck is this needed here?…, etc.), or not (often the case).
• At least one real world, detailed example: So many scripts/classes/etc. come with the most God awful, trivial, only-uses-one-aspect-of-the-code examples. These are just worthless. Period. Even when they are correct (which very often they aren’t because the code base changes at a 2.5x rate compared to documentation). Just one real example can negate reams of missing documentation, really.
• If the script/class is of a framework-ish or application structure-ish type I would like to have a small (empty) reference implementation to start with. This should be structured using the ‘best practices’ for your code. This will give me something to hang test code on and will get me up to speed in very short order (even if I don’t understand what I’m doing yet). Be sure to take into account other ‘best practices’ when you set this up (normal web server layouts, code references, etc.), and document those that you don’t adhere to.
• And in my dream world, I would like to see actual documentation. That is documentation that has actual text (not just the method/function definitions and their undocumented parameters) describing the inner-workings of your exquisite, hand-crafted code base. Even sprinkle on some working example code snippets.

Interesting that I was just mentioning Paul Jones and his various PHP related efforts, he has just announced a new one centered on PHP5, the Hive. Unfortunately I’m missing the initial PHP5 wave at the moment, waiting on more widespread deployment (hosting services, etc.). However given the quality of Paul’s other efforts and that Hive is the successor to the Yawp/Savant code line I will be watching very closely.

In his Hive announcement Paul stresses comprehensibility, which is definitely a positive trait in his other PHP efforts, and a very worthwhile goal that much of the PHP ’script’ world should aspire to. I’m glad he brings up this point in reference to Pear, as that is mostly what kept me from using Pear code for quite some time. Until you get over the Pear hump, Pear code is difficult to visualize. That is it isn’t apparent what Pear can offer you (or even what actually comprises Pear), what pieces/files you actually need if you think an element you’ve seen might be useful, or how to actually get the elements. Much of this could be remedied (disregarding actual package code complexity) at the Pear web site level, which suffers from a lack of higher-level information or documentation.