JimmyCrackedCorn
Posts: 583
|
| Posted: 03/08/2008, 5:37 PM |
|
I am curious as to what other CCS users think about the documentation. In the past 30 years I have used and written documentation for many, many software products and I feel the CCS documentation is in need of substantial improvement. When I voiced my concerns about the documentation to CCS Support they told me that they are happy with the documentation and have no plans to improve the documentation unless they hear from users about specific issues.
I understand that Yes can respond better to SPECIFIC suggestions so I would like to list a few of the things I'd like to see improved in the documentation. If any of you have things you'd like to see improved please add it to this list and let's see if we can help make this great product easier to use! (Or if you think I'm out in left field and the docs are just fine please say that!)
1) The new Ajax examples are welcome but they do not include the additional documentation like the previous example packs. The previous ones had a page or two describing how to recreate the example from scratch. I miss this in the new Ajax examples.
2) The new Ajax Show Modal documentation is an example of where the documentation should be expanded and thereby improved! It is basically a sentence "The Show Modal feature displays panel content in a modal window." and a properties table. For someone who just wants to quickly add a modal window to their project this does not really help you to get started. I had to dissect the example and managed to get a very basic modal window working. And through trial and error I think I figured out that the panel with the trigger and the panel with the modal window cannot share an update panel, rather they each need one. At least that's the only way I could get this to work. That would be nice to mention in the docs! What I need to figure out next is how to size, position and style the modal window and I have no doubt I will figure this out but wouldn't it be nice if the tool I'm using to save me time helped me figure this out quickly?
3) I find the examples to be very useful but often have to waste a lot of time dissecting them in order to figure out how certain features work. The result of this is I lose a lot of the productivity gains I'm supposed to realize by using CCS!
4) The documentation of the Flash Charts is a good example of sparse documentation! It is really only a bunch of screenshots along with very minimal information. I am very surprised to see such a cool new feature have only this one page in the documentation! Check out the docs for FusionCharts (http://www.fusioncharts.com/Docs/Index.html) to see how a feature like this could be properly documented!
5) Version 4 has been out for more than a month now and the Documents & Tutorials section of the web site only has version 3.2 PDF documents available. For those of us who like to print the documentation it would be nice if they kept this up to date.
6) Related to #4 above, several sections of the documentation could sure use updating to explain some of the cool new CCS features of the last two major versions (4.x and 3.x). With all of the powerful new features surely we can come up with more than 3 topics under Tips & Tricks!
7) As far as I can tell the Programming section has nothing about the new Ajax or other 4.0 features.
8) The Example Pack section of the documentation does not appear to be updated for any of the new features.
9) The Solutions section of the documentation does not appear to be updated for any of the new features.
10) The Update Panel, TabbedView and TabbedTab have not been added to the Component Reference section. (To be fair these have some documentation in the Ajax section of the User's Guide but what's the point of having a separate Component Reference if you are going to leave the new components out of it?)
11) In the Key Features of CodeCharge Studio section I don't see anything about Ajax features or Flash Charts but I do see that "CodeCharge Studio can be installed as an Add-In for Microsoft FrontPage". Really? I thought that support was discontinued for version 4.
12) While I'm on the Key Features of CodeCharge Studio section, the animated GIFs drive me crazy! They don't print properly, you cannot tell whether you are on frame 1 or frame 4 nor can you control the flow so their intended purpose of a mini-slideshow fails to deliver, and multiple animations on a page just is not a good thing in my opinion. I'd recommend inserting multiple images for each feature rather than animating them.
13) Generally speaking (I know I'm trying to be specific), I find the documentation has been barely updated since I first purchased CCS 3.0 and even at that time it looked like it had not been through a major update going from 2.x to 3.0. The result is new features like Ajax and Flash Charts feel "tacked on" rather than integrated. I'd vote for a complete rewrite of the docs; this is what most major product releases need.
This is just a start as I'm sure I can identify additional improvement areas when I get time. Please add any specific areas where you'd like to see the docs improved.
_________________
Walter Kempees...you are dearly missed. |
 |
 |
JimmyCrackedCorn
Posts: 583
|
| Posted: 03/08/2008, 6:12 PM |
|
A couple more that are admittedly quite minor but IMHO reflect a somewhat lax approach to maintaining good documentation.
14) In User's Guide under HTML Controls, the topics are mostly in alphabetical order but a few (Image, ImageLink, Line Break, etc.) are out of order. I know this is close to trivial but fixing it improves the docs! :)
15) Also in User's Guide click the Working with Builders link and you will see 8 builders listed in the right pane. But if you expand the Working with Builders topic in the left pane you'll see there are actually 13 builders documented. Again, not a big issue but one that reduces the effectiveness of the docs and causes me to have to spend more time searching for answers!
_________________
Walter Kempees...you are dearly missed. |
|
|
|
Stanj
Posts: 166
|
| Posted: 03/09/2008, 12:34 AM |
|
If you really know the product, the docs are useful but starting out with each change in features the community struggles until it builds a working knowledge of the system and shares their experiences on the forum.
Why not make a jump to a Wiki style on-line resource so users can build a knowledgebase as we learn? The accumulated wisdom that is now not easily accessible would suddenly be very easy to update and use. A base from which to begin could be the current CCS documents to which we could all contribute to quickly expand on the rather terse descriptions in the current docs.
For example, JimmyCC, you have discovered more about the Modal window than most of us so if written about as an entry under Modal windows, it would be a jump start for the rest of us and as we actually use it for something new discoveries would be added.
YesSoftware could either create a space for a Wiki on their site or we could do it as an independent community project. I am sure there are members who have excess web space and bandwidth available who would donate the resources.
Even if the unlikely event of YesSoftware giving the docs a high priority the community maintained Wiki would still be highly useful. I fully understand the problem of resource allocation within a small development company, new features, versions and bug fixes get the focus take priority over documentation of exisiting products.
_________________
Stan
St Petersburg Russia |
|
|
|
JimmyCrackedCorn
Posts: 583
|
| Posted: 03/09/2008, 1:33 AM |
|
Quote Stanj:
If you really know the product, the docs are useful
"if you understand...no explanation is necessary...if you do not...none is possible"
Yes keeps telling me Wiki is the way to go too but I have several concerns,
1) it will always lag behind the product release cycle because the developers will get even more lax when they know someone else is doing the documentation!
2) it will be inconsistent from an editorial style perspective
3) it will contain inaccuracies and potentially be intentionally spoofed (http://arstechnica.com/news.ars/post/20060801-7396.html)
I guess if Yes refuses to improve, and in fact they currently state that there is no need for improvement, this might be our only option but I would greatly prefer to have developer-provided docs with the Wiki used as a supplement.
Now back to the question on the thread...What does everyone think of CCS documentation?
_________________
Walter Kempees...you are dearly missed. |
|
|
|
TheunisP
Posts: 342
|
| Posted: 03/09/2008, 4:00 AM |
|
mmm here is my take on it - the doumentation is either written by the coders of CCS or domentation people.
This presents a problem since we all know that REAL CODERS don't do documentation. Also REAL CODERS don't bother with lesser beings e.g. QA, documentation people, users, bosses etc.
|
|
|
|
wkempees
Posts: 1679
|
| Posted: 03/10/2008, 4:58 AM |
|
still reading, but missing document pages on Ajax samples, agreed 100%.
Inconsistent with previous samples and inconvenient as well.
(JCC items 1,2,& 3)
_________________
Origin: NL, T:GMT+1 (Forumtime +9)
CCS3/4.01.006 PhP, MySQL .Net/InMotion(Vista/XP, XAMPP)
if you liked this info PAYPAL me: http://donate.consultair.eu
|
|
|
|
wkempees
Posts: 1679
|
| Posted: 03/10/2008, 5:09 AM |
|
Wiki has been discussed a few times, I even think it was opted for by Yes(??).
How many are willing to govern the added text, if a WiKi would emerge?
I am willing to donate high speed high availability space and register a domain for it.
And pre-promise to release it back to Yes if they so ask.
(taking the basic cost)
Can we, are we allowed to, spunge the docs into a Wiki and build from there?
Walter
_________________
Origin: NL, T:GMT+1 (Forumtime +9)
CCS3/4.01.006 PhP, MySQL .Net/InMotion(Vista/XP, XAMPP)
if you liked this info PAYPAL me: http://donate.consultair.eu
|
|
|
|
TheunisP
Posts: 342
|
| Posted: 03/10/2008, 3:45 PM |
|
mailed support just to give me a quick step by step (just fil in the blanks type of thing) regarding the damn modal and call back procedure - no luck - was sent back to the example
don't they think I tried the damn example?
|
|
|
|
TheunisP
Posts: 342
|
| Posted: 03/10/2008, 3:48 PM |
|
ps. Walter why pre-promise to give it back? I say we monetize it and pay our licenses with it - then sell it to Yes - wait for it to go out of date and start the whole process again 
|
|
|
|
wkempees
Posts: 1679
|
| Posted: 03/10/2008, 4:36 PM |
|
Anyone second that?
wiki is already in place and running, though empty.
Do we want separte wiki for 3x and 4x or just 4x and describe differences?
How about the content (I have it) is it copyrighted, can we use it as a base?
Any idea's any comments Peterr?
Everyone else, any idea's on the desired content?
Proposal is inital content = docs4, open to all for edit.
Let's get together!
Hit me with idea's
_________________
Origin: NL, T:GMT+1 (Forumtime +9)
CCS3/4.01.006 PhP, MySQL .Net/InMotion(Vista/XP, XAMPP)
if you liked this info PAYPAL me: http://donate.consultair.eu
|
|
|
|
andrewi
Posts: 162
|
| Posted: 03/10/2008, 4:50 PM |
|
The documentation is very weak.
I've just attempted a modal form and failed to get it to work using the documentation "page" (line). Searched for Modal in the forum and found this article - and I agree with the opening sentiments.
I really do wish they'd improve the documents. They've put all that effort into the product, and then leave us to guess how to use it. There are some great features in it that I didn't discover for years until someone on the forum mentioned them!
|
|
|
|
TheunisP
Posts: 342
|
| Posted: 03/10/2008, 5:19 PM |
|
I think this is maybe the way to go >> just 4x and describe differences
the reason behind going for this is that there are no real differences between the stuff that were carried from 3 to 4 - except for new technologies and components
ps. Walter on a more serious note (than my previous post) I do believe that we should copyright the content with free use for CCS users - I will have a really bad taste in my mouth if the content we put together just appear like by magic in some other place or am I being nasty on this?
|
|
|
|
wkempees
Posts: 1679
|
| Posted: 03/10/2008, 5:29 PM |
|
T,
Serious note taken.
I do not want to offend Yes Software, so I step carefuly.
How can we copyright something that is copyrighted?
Is there a form in wich we copyright only the extended text and who's copyright should it be?
Legal stuff, in a foreign country/language not my forte.
Will proceed silently with Docs4, then we move from there.
Any takers?
Walter
_________________
Origin: NL, T:GMT+1 (Forumtime +9)
CCS3/4.01.006 PhP, MySQL .Net/InMotion(Vista/XP, XAMPP)
if you liked this info PAYPAL me: http://donate.consultair.eu
|
|
|
|
JimmyCrackedCorn
Posts: 583
|
| Posted: 03/10/2008, 5:32 PM |
|
not sure how much I could contribute but I'd be willing to write something each time I spend a few hours figuring out a new feature!
could we also post small working examples with an article?
_________________
Walter Kempees...you are dearly missed. |
|
|
|
wkempees
Posts: 1679
|
| Posted: 03/10/2008, 5:39 PM |
|
J,
All WikiMedia options.
So I think yes, as editor you could write up example and then put links at the approprate place(s)
I will enable as much useful options as available through wikimedia, above all image uploading.
Walter
_________________
Origin: NL, T:GMT+1 (Forumtime +9)
CCS3/4.01.006 PhP, MySQL .Net/InMotion(Vista/XP, XAMPP)
if you liked this info PAYPAL me: http://donate.consultair.eu
|
|
|
|
TheunisP
Posts: 342
|
| Posted: 03/10/2008, 5:40 PM |
|
W, I'm with you - maybe take the lead - create a sample format e.g. lets take a function/component and document it, create say 1) where to find it? 2) placing it? 3) a short step by step? 4) then extended properties explanation and then an extendable tips/gotchas?
1a) purpose of compenent?
try and make it as lanuage independent - run maybe with a high level spec 'language'
ps. can we start with the generic ajax stuff, I'm still worried about putting a lot of faith in the add-on lib's e.g. yahoo? and the other one?
|
|
|
|
TheunisP
Posts: 342
|
| Posted: 03/10/2008, 5:43 PM |
|
W, on the other issue: we put down a terms & conditions of use, the author community takes 'ownership' and the work created can not be used in any commercial work, neither can the work be expanded on for commercial purpose - there is a specific Creative Commons License for it - to protect work created from commercial exploitation
|
|
|
|
Oper
Posts: 1195
|
| Posted: 03/10/2008, 6:08 PM |
|
CCS Documentation for a Experience User is Perfect (everthing is there)
everthing i need to know is there and easy to find.
for a Beginer worth a Penny
in my opinion Yes could sale more if the Documentation is worked for beginner (maybe i'm wrong)
if you need a server space for the wiki we own like 5 server in one of the best datacenter, but like i said one time if yes dont take the responsability of the maintenace of the wiki project will felt down sooner (notice i use sooner)
_________________
____________________________
http://www.7bz.com (Free CMS,CRM Developed in CCS)
http://www.PremiumWebTemplate.com
Affiliation Web Site Templates
Please do backup first |
|
|
|
RonB
Posts: 228
|
| Posted: 03/11/2008, 8:27 AM |
|
For CCS3 the documentation was fine. For CCS4 there is a problem. Ajax features are only marginally explained. New features suffer from lack of documentation. To me it's important to have good documentation available even more so when you introduce new features as important as the ajax/yui/prototype features.
I feel they should have payed more attention to the documentation before releasing CCS4. Working with the prototype updatepanel is tricky and more often then not things stop working in my grids when I introduce the update panel. This should have been one of the most important steps forward for CCS. Now I've started to revert to using iframes etc just so I can finish my projects.
I'm sure I'm missing something but since there is next to no documentation, debugging and researching what it is thaI'm doing wrong takes up time I do not have. CCS is a RAD tool. It should not require dropping the rappid from that term to make sure your stuff still works.
|
|
|
|
THX1138
Posts: 37
|
| Posted: 03/11/2008, 9:15 AM |
|
As a token noob, i find the documentation to be lacking. I have read it front to back and while i have been able
to solve some of my problems by trial and error, there are other simple things which I can not make sense out of.
I approach this as one who has no programming skills (html is not coding)
The documentation would be much improved if there was code snippet examples in all the component references.
Given the authentication system built in to CCS, user level could be chosen by the reader, thus allowing selective
display of information so that experienced users dont have to read noob level examples.
|
|
|
|
ReneS
Posts: 225
|
| Posted: 03/11/2008, 11:01 AM |
|
Where is Peterr in this discussion? I really mis his involvement in this discussion.
Would be nice/essential to hear something from Yes....
Rene
|
|
|
|
JimmyCrackedCorn
Posts: 583
|
| Posted: 03/11/2008, 11:22 AM |
|
Quote ReneS:
Where is Peterr in this discussion? I really mis his involvement in this discussion.
Would be nice/essential to hear something from Yes....
Rene
I don't mean to speak for Peterr but I can say when I asked support about documentation improvements I was told in no uncertain terms that they feel the docs are just fine and don't need any improvement! I am hoping if enough of us provide specific comments here on improving the docs then maybe they will reconsider that position.
_________________
Walter Kempees...you are dearly missed. |
|
|
|
datadoit
|
| Posted: 03/11/2008, 4:32 PM |
|
While I don't disagree that the documentation isn't up to snuff, let's
not forget how we all hooted and hollered beggin' for AJAX support in
CCS. Well, we got it in relative short order!
I'm certain the documentation is forthcoming.
|
|
|
|
JimmyCrackedCorn
Posts: 583
|
| Posted: 03/11/2008, 6:38 PM |
|
Quote datadoit:
I'm certain the documentation is forthcoming.
Don't be too sure! Here is the exact comment I got from Yes Tech Support after I complained about a lack of Ajax documentation,
Quote :The Ajax documentation in CCS is quite complete and will not be updated unless we find new things to add. Using Ajax is just so simple that we don't know what can we document; all you need to do is click on the "Feature Builder" and follow couple steps.
We argued back and forth through several messages and I was not very pleased with the responses I got. So I thought I'd start this post and see whether I am the only Yes customer who believes their documentation needs improvement.
My general impression is this product was pretty well documented a couple of versions ago but the 3.x and 4.x features just appear to be tacked onto the existing documentation. My opinion, based on my own experience in both using and writing tech docs, is that a more complete rewrite of the docs is in order. Yes definitely does not agree though so maybe a user-supported wiki is the best we are going to get.
_________________
Walter Kempees...you are dearly missed. |
|
|
|
ckroon
Posts: 869
|
| Posted: 03/11/2008, 8:10 PM |
|
I have often been tempted to write a CCS guide for the Utterly Complete Helpless Newbie.
So I am down with helping out with a WIKI.
I like the idea of the first page being a selection of what level Docs/Guide you want access to.
_________________
Walter Kempees...you are dearly missed. |
|
|
|
wkempees
|
| Posted: 03/13/2008, 11:06 AM |
|
http://forums.codecharge.com/posts.php?post_id=94929
|
|
|
|
Suntower
Posts: 225
|
| Posted: 03/13/2008, 2:17 PM |
|
I complained in -exactly- the same way when I first bought CCS. Now that I'm a -bit- more experienced I appreciate the help more. It's like a dictionary... it's all in there if you already can speak the language. But have you ever tried to learn a language from a dictionary?
I personally think Yes has shot themselves in the foot 1000 times over the years with the lack of fleshed out examples. Pity. Great product---as we all know.
---JC
Quote Oper:
CCS Documentation for a Experience User is Perfect (everthing is there)
everthing i need to know is there and easy to find.
for a Beginer worth a Penny
in my opinion Yes could sale more if the Documentation is worked for beginner (maybe i'm wrong)
_________________
---On a campaign for more examples and better docs! |
|
|
|
mclare
Posts: 12
|
| Posted: 03/28/2008, 1:53 AM |
|
THANK GOD!!!!! I thought I was fricking insane???? I am glad you brought this up JimmyCC.
I actually had to pay YesSoftware for a couple of page additions using ffeatures that are clearly in here and written about, yet I can't seem to make work as described in the "Documentation"
I too discovered about the two separate update panels, however I have not been fortunate enough to get it to work. I just sent a projerct to them to get a simple Modal to work after struggling with it for four days.... Yes four days.... Wasted....
Well I vote for a complete re-write of the docs. I have been with CCS since 2.2 and it's always been crappy documentation. Sorry CCS guys, but your docs are crap. It's a fantastic program, cobbled by poor documentation. I am sure so much more could be done with it if developers knew all it can do. After 6 years using it I am discovering new features everday, barely mentioned in the docs.
You got my vote JimmyCrackedCorn!
|
|
|
|
Stanj
Posts: 166
|
| Posted: 03/28/2008, 5:14 AM |
|
The discussion about the wiki might be better to move to the Woki itself since the topics needed to be discussed are more about structure and configuration than about CCS.
I lost track of this thread and did not realize Wiki was up and ready to start entering articles.
An article style and organization should be decided on before articles are posted, as well as a framework of topic catagories.
A few questions:
Would it make sense to follow the layout of topic catagories used in the CCS documents or does anyone have a better idea?
Is there a possibility to use a current copy of the documentation as seed documents from which to add comments, examples, tips and tricks in Wiki style?
The way the PHP.net allows comments by users after each function and feature is a nice model. I've learned more from those comments than the documentation itself.
Keeping activity up will likely require keeping the format as simple as possible so adding or commenting does not require a full blown article and that one article covering the full range of user levels. Some suggested beginner pages and more advanced pages based on user selection. Isn't that making it more complicated than needed? if a beginner is treated to a basic definition at the top(current CCS reference possibly but open for editing to put it into more user friendly descriptions), examples and notes/comments below would be useful for any experience level. The current programming and component reference is a good starting into which a lot of people probably have suggestions or comments on the function's use or its limitations.
After a style is decided on, and a few seed articles are added, I suspect the ice would be broken and many people would contribute. Keeping it simple fits into the notion that doc are harder and more time consuming than coding, and is normally avoided at all costs by the people who know best what the docs should contain.
Just a few thoughts about an exciting project....
_________________
Stan
St Petersburg Russia |
|
|
|
wkempees
Posts: 1679
|
| Posted: 03/28/2008, 8:30 AM |
|
Stan agreed, please repost in the Wiki itself and we'll decide upon a format.
Walter
_________________
Origin: NL, T:GMT+1 (Forumtime +9)
CCS3/4.01.006 PhP, MySQL .Net/InMotion(Vista/XP, XAMPP)
if you liked this info PAYPAL me: http://donate.consultair.eu
|
|
|
|
