scaswell1
11 Aug 2009, 7:47 AM
To the Ext GWT team:
It is my foremost belief that upon purchasing a product or licensing thereof, which is advertised as having 'Well designed, consistent and fully documented source code', I ought to be able to surmise the usage of any of that product's features via a quick and simple perusal through said documentation.
Having said that, I will say this: in the absence thereof, in the lack of the clearly advertised and therefore implicitly guaranteed complete documentation, I would expect the product's support pages to cover said promise in an in-depth, if not thorough, manner. In the case of Ext GWT, that would be the 'Learning Center' pages. Regardless of the fact that these pages are described as 'Community' pages, I would expect a somewhat concerted effort to populate these pages with at least semi-meaningful and completely useful information. By definition, the Ext GWT team is part of the community.
The most atrocious example of documentation failure are the Templates and XTemplates. It is not enough simply to add documentation to every member, function, and constructor of a class for it to qualify as 'fully documented source code'. There needs to be an enumeration of every tag that is valid in the XTemplate, with descriptions and example usages. It is not reasonable to expect the developers to research ExtJS, view those documentation pages, and then waste valuable development time practicing and sandboxing code to detect differences in API implementations. This is not what is paid for by a company purchasing a commercial license, and is counter productive to the goals of an open source product.
I make these comments purely as constructive but frustrated criticism. These deficits are a pronounced and glaring shortcoming of an otherwise wonderful product, and are a detriment to the success of Ext GWT, the usage thereof by developers, and the credibility of its open source statement. The fact that the Ext GWT roadmap does not indicate an improvement upon these flaws is surely a turn off for both potential new users as well as continued users.
It is my foremost belief that upon purchasing a product or licensing thereof, which is advertised as having 'Well designed, consistent and fully documented source code', I ought to be able to surmise the usage of any of that product's features via a quick and simple perusal through said documentation.
Having said that, I will say this: in the absence thereof, in the lack of the clearly advertised and therefore implicitly guaranteed complete documentation, I would expect the product's support pages to cover said promise in an in-depth, if not thorough, manner. In the case of Ext GWT, that would be the 'Learning Center' pages. Regardless of the fact that these pages are described as 'Community' pages, I would expect a somewhat concerted effort to populate these pages with at least semi-meaningful and completely useful information. By definition, the Ext GWT team is part of the community.
The most atrocious example of documentation failure are the Templates and XTemplates. It is not enough simply to add documentation to every member, function, and constructor of a class for it to qualify as 'fully documented source code'. There needs to be an enumeration of every tag that is valid in the XTemplate, with descriptions and example usages. It is not reasonable to expect the developers to research ExtJS, view those documentation pages, and then waste valuable development time practicing and sandboxing code to detect differences in API implementations. This is not what is paid for by a company purchasing a commercial license, and is counter productive to the goals of an open source product.
I make these comments purely as constructive but frustrated criticism. These deficits are a pronounced and glaring shortcoming of an otherwise wonderful product, and are a detriment to the success of Ext GWT, the usage thereof by developers, and the credibility of its open source statement. The fact that the Ext GWT roadmap does not indicate an improvement upon these flaws is surely a turn off for both potential new users as well as continued users.