Please Get Someone To Write Your Documentation

You are evidently a genius in programming, but whoa...this documentation is really hard to comprehend and follow.

You seem to make many assumptions that the reader already understands your system.

Get someone who is unfamiliar with your system to write the documentation as they understand it - as taught to them by you. This type of documentation is guaranteed to be understand.

Am I alone on this idea or do others find this documentation extremely hard to follow?

No you're not.

I guess genius in programming would be someone who writes the code which is so easy to understand that it does not require any documentation. So its definitely not me :-)

I agree that documentation is a huge problem and agree with your advice. BTW if anybody can recommend a good technical writer that may help a lot.

However, sorry to say that, but I will not be doing much work on the documentation until 2.0 beta is out. So maybe its better to wait couple of months if you are lost with the current one :-(

I do have to admit its a little hard to follow. It helps if you know some CCS and JavaScript. Even some good programming skills will help you get the hang of it.

However, I'm coming up to speed on this and I have to admit its brilliant. I even like the sections here where you can see example code, edit it if you want and see the results.

If I hadn't seen this with my own eyes, I would never thought it was possible without Java!

Once in a while the documentation issues pops in here. The need for documentation depends on where you are yourself as a programmer.

For example do you know javascript deeply
Do you know inheritance and event handling
Do you take the time to find example code and play with it.

The future of 2.0 and beyond sounds healthy the choce of making documentation who fits everybody needs and the wish to go ahead is a hard one to make.

Personally I like the framework. Although I am experienced not everything was clear to me in the beginning. But when you are play with the code and try to make the extensions you want you will find out how to do so.

Documentation is also based on the things you want everybody wants to change some thing e.g. highlighting (layout things), editing, add/search/filter/delete, multiple grids, cross browser questions, server side questions, event questions. Maybe a documentation in the form how can I ... will do.
But if you look at this forum closely and take your time and analyse the sample codes people provide you can make use of the framework very well and use the Search button/
Maybe a good moderator and crack (not Alex) he likes coding and is good in making superb code can reshape sort this forum in a How to .... support guide (with screen shots of the code). I don't mean a forum like this must disappear.

Documentation is not a great issue here as code is quite easy to understand. Alex u have done great job by developing this great Grid Controller.
Cheers...:)

Version 2 is out and without documentation, only a reference... no how-to's. Sad... very sad.

There is a directory with many "how-to's" and one with 5 pages of code, didn't you look in the Examples directory?

Yes I looked in the examples directory and I learned a lot. But there are things that need some explanation. For example, where is documented the "onCellValidated" method of the grid?

Your right, there are some methods that are not covered in the Quickref files. onCellValidated is fired after you make a change to a cell value. There is nothing else to document as you supply any code that you want to execute, it's just an event that triggers. For me, I would just set a flag in onCellValidated so that I know the row was changed, then when they move to another row (onSelectedRowsChanged) I would send back the changed data to the server, assuming something was changed in the row.

One thing that I find very annoying with the documentation is that it only lists method names, not arguments. That's great that you have a setPosition() function. What do I send it? Height, Width? Width, Height? HeightxWidth? Can I send percentages?

While these are easy questions to figure out, a lot of developers are on extremely time-sensitive deadlines and too much documentation is better than not enough.

(Of course, too much documentation is worse than just the right amount, but this isn't the right amount).

setPosition(Left, Top);
setSize(Width, Height);

and in both cases you can not use percentages! The values passed in get "px" appended to them, they are expecting numbers. If you need to use percentages then you are going to have to use setStyle().

Jim, I know how they work. :-) My point was that the documentation on this site isn't well written at all. There is the QuickRef folder, yes, but QuickRef != full documentation. None of the online docs provide argument types or lists, nor return types.

I fully agree with Eric, and sincerely appreciate Jim's efforts to compensate for lack of full documentation.

What about setting up a wiki and be able to document every function with examples? I think many of us will collaborate in completing information or providing examples of code.

The documentation pages are wiki and I made it open for everyone to edit - each page now has 'edit this page' and 'page history' commands at the bottom right. If you can help with examples or any other documentation bits - I would very much appreciate this!

Alex,

I see that we can edit info for pages that are already there, but what about missing pages all together? You have recently mentioned onCellValidated for the grid but I can't find any mention of it in the samples or in the on-line docs. How would we go about adding that to the documentation system? Are there any other hidden gems like that, which we might like to know about?

I, too, recommended that documentation be written for this "product".
I sent an email to Alex and discussed the option of my partner and I writing the documentation. I am a Software Engineer of over 20 years and she is a Technical Writer with as many years. We have written documentation for Bay Networks (now Nortel), Kurzweil Intelligence, a host of communications and tele-communications companies. I, currently am developing a web-based network management portal for a private school. She is currently editing and writing for a premier Information Technology magazine. We have the talent, experience and systems perspective. We recommended that several documents should be written. A User Guide for those users who want to get started right away. A Developers Guide for those users who want to know the verb/API interface and want to know how to add functionality and a pure Reference Guide , cleanly organised which, provides much of the information on the site.

I want to call an Action with a id as a parameter on double clicking the row. Please tell me how to do it.

Hi Guys

Yup i'm afraid i'm another that is finding this documentation hard to follow.

The problem is a destinct lack of quality examples. The product is excellent and deserves to be regarded higher with better documentation.

I love the fact that the system is browser independant with known bugs published. I also love your openess to accept the failings.

Maybe a way to go is to integrate this into Visual Studio so that the system suggests the flow of the objects. Just a thought...

Txs

Must agree a bid...

It is not so hard to use your great controls... It is quite easy to put them in and do what you need from them... There is only one thing... (but ture, I also sometimes asked for something I was able to solve just looking carefuly into the code but...)

The examples does not show all possible setups, all keywords to be passed into the methods... That way I most time spend by searching or asking...

Otherway... What I know I use now and it takes minimum time to do so, but if I need something I've never tried or never had seen any expample, than it is line search a pin within the mound :(

At last it would be great do add more explanations to properities an methods... All the rest we can get through.. ;-)

BTW: But go on... Great Job !!

Best Regards...