Documentation

[Stan]

I would like to see MUCH more documentation. ALL PRODUCTS. I'm starting to see more done within the last 4 or 5 months but still very sparse. I have bought probably 3/4 of what WebAssist sells. Obviously I see value or I wouldn't be coming back. However you can do SO much better. I've never seen a developer who liked to document and many of them feel that it's a waste of time.

In particular, I bought the PowerStore. I already own most of the tools but I thought what the heck, here's an opportunity to learn from the masters, right? Wrong! It's like fighting tooth and nail for everything I can pull out of it. I'm looking at the SQL...nice. But what is it? "ProductStock, ProductLive, ProductUnlimited." No comments. I don't know what they are. The only way to find out is guess, dig and test. LOTS of work when a simple comment would have done the job. And have you looked at the PHP code? Did anyone ever hear about requiring a percentage of code to be commented before it can be checked in? This code looks like it would be about 2%.....maybe.

Enough said. Your product isn't shrink wrapped software. Much of the value is in the knowledge you impart. DOCUMENT, DOCUMENT, DOCUMENT.

[Neil Beadle]

Hi Stan,

We are working hard towards improving documentation for all of our products. As you have noted, the amount of documentation we have produced has increased significantly over the past 6 months.

However, our focus is to develop products that give users the power to be successful on the web. With PowerStore, we are trying to make it easier for our customers to sell products on the web, not provide code to be pulled apart as a learning mechanism. From a documentation standpoint, we are committed to providing How Tos, Roadmaps, and various other training materials, to ensure that our customers be successful in implementing the products they have purchased.

This is not to say that we can't or won't include more comments throughout the code of our products, but as of right now it is not our primary focus.

[Stan]

Neil, please don't tell me that you think the PowerStore is sufficient all by itself without anyone making any changes. Of the four bullet points promoting the PowerStore one says:

"PowerStore was built with a wide variety of our Dreamweaver plug-ins and therefore can be modified, customized, and extended with these plug-ins."

If for no other reason than to facilitate your own development efforts it should be documented. Nor is PowerStore unique. NONE of your code is sufficiently documented. It's not hard and well worth the money to build a tool which produces a per cent documentation number for any source code.

Even if NO customization were done, there is no information about the database and how it was intended to be used. As an example: In the products table a field is named "ProductUnlimited." What do you suppose I as a powerstore user should put in that field. True/false meaning sell without limit? I don't know and how is it going to be used by the code. I don't know. How about a field called "ProductLive." Is that True/false for pigs and goats. Who knows?

I'm being hard on you but for good reason. I like WebAssist and I only wish to tell you what I perceive as ways to make you better. The path to improvement must first include acceptance. You can't make constant quality improvement until you accept that you need to improve. Your statement "We are working hard towards improving documentation for all of our products." Is very positive. But deflecting criticism of PowerStore is very negative.

What happens to these comments. Do any product managers ever read them? Do you ever take them to Ray and have him read them? Be an agent of change.

While you say that it isn't your primary focus to document code, I would hazard a guess that the same worst practices that produced your nearly comment-less code continue as standard practice today on new code going forward. In my opinion, and I'm not without experience to make my opinion valid, the single biggest contribution to poor code is lack of documentation.

Thanks Neil, I hope you don't take this personally. I'm just trying to help.