Please Get Someone To Write Your Documentation
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?
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 :-(
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!
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.
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?
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).
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().
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.
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 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.
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...
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 !!
This topic is archived.
Back to support forum
Version 2Looking for AW 2.6 ?
The old site is here.