close ad
 
Important WebAssist Announcement
open ad
View Menu

Technical Support Forums

Free, outstanding support from WebAssist and your colleagues

rating

Documentation

Thread began 6/24/2009 1:02 pm by anonymous | Last modified 6/25/2009 6:43 pm by anonymous | 1920 views | 2 replies |

anonymous

Documentation

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.

Sign in to reply to this post

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.

Sign in to reply to this post

anonymous

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.

Sign in to reply to this post

Build websites with a little help from your friends

Your friends over here at WebAssist! These Dreamweaver extensions will assist you in building unlimited, custom websites.

Build websites from already-built web applications

These out-of-the-box solutions provide you proven, tested applications that can be up and running now.  Build a store, a gallery, or a web-based email solution.

Want your website pre-built and hosted?

Close Windowclose

Rate your experience or provide feedback on this page

Account or customer service questions?
Please user our contact form.

Need technical support?
Please visit support to ask a question

Content

rating

Layout

rating

Ease of use

rating

security code refresh image

We do not respond to comments submitted from this page directly, but we do read and analyze any feedback and will use it to help make your experience better in the future.

Close Windowclose

We were unable to retrieve the attached file

Close Windowclose

Attach and remove files

add attachmentAdd attachment
Close Windowclose

Enter the URL you would like to link to in your post

Close Windowclose

This is how you use right click RTF editing

Enable right click RTF editing option allows you to add html markup into your tutorial such as images, bulleted lists, files and more...

-- click to close --

Uploading file...