Jason,
sounds to me like you want to be the first recipe maker!
Jan Aleman:
And looking forward to examples how you think the documentation can be improved, please be as detailed as possible.
Jan,
Since you’re looking for specifics: one critical thing I find that is missing from the documentation on the website and elsewhere is a detailed list of the browsers and versions that are supported by the Servoy Web Client. Hopefully this is something that you can rectify quickly. I’ve opened a ticket on this (233285).
Thanks,
Corey
Yeroc:
Jan Aleman:
And looking forward to examples how you think the documentation can be improved, please be as detailed as possible.Jan,
Since you’re looking for specifics: one critical thing I find that is missing from the documentation on the website and elsewhere is a detailed list of the browsers and versions that are supported by the Servoy Web Client. Hopefully this is something that you can rectify quickly. I’ve opened a ticket on this (233285).
Thanks,
Corey
Good point, we will add that. Mainly we support all browsers that implement the html standard correctly, in addition we try to support all most used webbrowsers, right now that would be:
IE 6,7,8, Safari, Opera 9,10, Firefox 3, 3.5 , Google Chrome, Camino, Webkit
Jan,
Jan Aleman:
Good point, we will add that. Mainly we support all browsers that implement the html standard correctly, in addition we try to support all most used webbrowsers, right now that would be:IE 6,7,8, Safari, Opera 9,10, Firefox 3, 3.5 , Google Chrome, Camino, Webkit
Thanks. My personal experience is that none of the browsers implement the html standard perfectly which is why we need to know which ones are officially supported and tested by Servoy.
A bunch of Eclipse cheat sheets would be helpful I think. For things like:
Some things lend themselves much better to be shown/led through than hunting through documentation. Even online documentation.
I’m questioning whether Servoy is still committed to improving the documentation.
While the searchable documentation at http://wiki.servoy.com/ was a big step forward it seems to be languishing. By my count there have been just 9 publicly-available pages modified or created over the last 4 months. This might be acceptable if the documentation were already complete but it’s not. I know Jan asked for specific areas where the documentation needed improvement but I’ve come to the conclusion that an exhaustive list is far too much work and if the vendor (Servoy) can’t see the shortcomings themselves then we’ll never reach the point where the documentation is adequate.
For example, the other day I was searching for options to create a dynamic valuelist so I went looking on the wiki for documentation on valuelists based on a global method (I knew about this feature because it’s a visible option in the IDE when creating a valuelist). Searching for “valuelist global” turned up nothing. Next I tried searching on simply “valuelist”. The first hit took me to http://wiki.servoy.com/display/public/DOCS/ValueList and here’s where I start getting frustrated. All it lists is the API for a valuelist with absolutely no description of what a valuelist actually is. This is true of many of the pages: there’s a simple listing of API methods with a description but no description of the overall concepts embodied by the class. There is at least one page that does have a good description (Relations: http://wiki.servoy.com/display/public/DOCS/Relation) but there’s been no effort over the last 4 months to expand or add descriptions to the other key concepts/objects.
In the end, the only relevant documentation I found on a valuelist based on a global method was by searching on the forums and by examining the sample code generated in the IDE and setting breakpoints in the code to examine the argument inputs in various scenarios not documented in the sample code (ie. what happens when entering find mode etc.) This is not an efficient way to get answers and may well prove insurmountable for inexperienced developers!
I know Servoy has heard this same message over and over again but I hope that somehow hearing it yet again will spur some action.
Thanks,
Corey
Corey - best of luck with this one Bud!!!
100% behind you in all of your comments. All the Servoy guys are exceptionally pressured just getting software out the door and especially developing to a deadline like Servoy World in Feb next year. All power to their elbow’s.
But… you are right.
- Reverse engineering sample solutions is NOT documentation.
- Trawling the forums is NOT documentation.
- Going, cap in hand, to those good enough to give of their time on the forum for support and how too’s is NOT documentation.
- Wiki of ‘reference’ is NOT Developer documentation (it’s function reference).
I now don’t believe Servoy is capable of creating developer documentation, I don’t think they have the skills in-house to do that, and because of their focus on new development of Servoy, they will probably never dedicate the time and effort to do so.
IMHO the best solution would be for Servoy to commission one or two of the most knowledgeable from our ranks (the most prolific on the forums probably) to de-construct the sample solutions and write a developers manual around each with specific how to’s rather than simple references to functions and return values. Every other half decent language I’ve ever come across has this either developed in-house or externally. If this was developed and published section by section we could conceivably have a proper development manual in place in a matter of months.
Adrian McGilly wrote a brilliant starter manual years ago (for version 3.5)and something like that brought up to date and a little more focused an developing a solution would be excellent too.
I’m not holding my breath…
for the global method valuelist the best doc is currently to let the developer generate the method.
If you do that then all the doc that you need is there. It tells exactly in the java doc which modes there are and it has an example for all 3 of them.
i agree that http://wiki.servoy.com/display/Serv51/J … obalMethod is wrong and not good enough
I fixed this in the java doc now so that it is in sync with what you get when you generate the method.
All those docs (so the java doc) are by the way not done by hand through the wiki, those are generated from our source code itself.
jcompagner:
for the global method valuelist the best doc is currently to let the developer generate the method.All those docs (so the java doc) are by the way not done by hand through the wiki, those are generated from our source code itself.
This doesn’t help - especially to newbies and ‘4G’ developers. Please Servoy take (at least) Kahuna’s advice:
Kahuna:
IMHO the best solution would be for Servoy to commission one or two of the most knowledgeable from our ranks (the most prolific on the forums probably) to de-construct the sample solutions and write a developers manual around each with specific how to’s rather than simple references to functions and return values. Every other half decent language I’ve ever come across has this either developed in-house or externally. If this was developed and published section by section we could conceivably have a proper development manual in place in a matter of months.
JC
Johan,
Thanks for responding. I don’t want to dwell too much on the specific example I raised as that’s merely one example of many to help drive home the point. I’m hoping someone like Jan will respond in some kind of official capacity with an acknowledgement and statement of direction.
Nonetheless…
jcompagner:
for the global method valuelist the best doc is currently to let the developer generate the method.
If you do that then all the doc that you need is there. It tells exactly in the java doc which modes there are and it has an example for all 3 of them.
When I referred to “sample code generated in the IDE” that was what I meant. Even so, the sample code doesn’t provide answers to the following questions which should be part of the documentation since the answers are unintuitive:
- What is the “realValue” parameter when the field in your table is null? It turns out that the answer is “-1”. (It may be important to know this so you can avoid an unnecessary query.)
- When is my global method called when a form enters find mode and what are the parameters? No mention at all is made of find mode in the sample code. Again, through experimentation I was able to determine that when entering find mode the “record” parameter passed in is not actually a JSRecord at all! Since this behaviour isn’t documented I don’t know whether this is a feature I can rely on or merely a bug (being able to differentiate when in find mode is important because I need to return a different valuelist based on whether I’m in find mode or not.)
Corey
Kahuna is in Right.
The documentation is not important for Servoy leaders.
Servoy documentation don’t exist since Servoy 4 , and they are talking about Servoy 6 in the February 2011
annual conference.
Here are some beans of doc:
Tutorials nothing … ( See tutorials in Servoy Wiki ).
Documentation about Servoy on Linux … nothing.
( Servoy Developer 5 crashed when you run SmartClient on any distribution with gnone,
only works with KDE ), excellent for solution testing.
Webinars no comments.
For me, Developers are the most important piece to obtain the final porpouse that is a Excellent Solutions
for our CUSTOMERS , and the best part is that Servoy Sell a lot of LICENSES.
Sorry for my bad English …
[edit: removed horrible usage of colors and fonts, please refrain from doing that this is not a primary school]
I’m glad someone re-opened this discussion. I was excited when I heard about the WIKI being created many months ago. But, it has not lived up to its potential from what I have seen. I have learned what I know about Servoy though experimentation and creating my own developer tools. My fellow programmers (some who come from 4GL backgrounds) still think of Servoy as this “black box” that they don’t quite understand what is happening beneath the surface. This is unfortunate. Other platforms such as FoxPro, .NET, Flash, PHP all have extensive documentation with in-depth explanations, code examples, tips, gotchas, etc.
I hope this can be improved upon as time goes on (especially when Servoy 6 is released). Until then I’ll continue to figure it out on my own.
This is a bit like beating a dead horse. We have said we are working on the documentation and we have good progress. We have asked about constructive suggestions and are processing them. All people at Servoy with technical skills contribute to the documentation.
Armin: with all due respect, a lot of people have tried to help you, you did not follow up on this thread:
http://www.servoy.com/forum/viewtopic.php?f=11&t=15047
Also I even had a personal email conversation with you and you did not reply to my last email, your complaining is quite out of context. And for your peace of mind: we spend more time writing and documenting Servoy than selling licenses.
Yeroc:
- What is the “realValue” parameter when the field in your table is null? It turns out that the answer is “-1”. (It may be important to know this so you can avoid an unnecessary query.)
[/quote]-1? that looks very weird to me, then that is the real value of the dataprovider
Where the dataprovider is null the global valuelist is not queried… for that value
So i don’t know where that -1 really comes from but that is not something we do on purpose when the dataprovider is null
In what context do you use the global method valuelist? what component in what kind of client uses it where you get the -1So the doc for this is should be correct, we query with a real value when we want to know the display value of a real value (and that real value != null)
We currently dont really support a “null” default value, sending -1 is a bit weird because that could be a valid realvalue just fine…Yeroc:
- When is my global method called when a form enters find mode and what are the parameters? No mention at all is made of find mode in the sample code. Again, through experimentation I was able to determine that when entering find mode the “record” parameter passed in is not actually a JSRecord at all! Since this behaviour isn’t documented I don’t know whether this is a feature I can rely on or merely a bug (being able to differentiate when in find mode is important because I need to return a different valuelist based on whether I’m in find mode or not.
[/quote]Yes what you get is the same as when you are in find mode, you get the “find record” and yes that is not a real record so it doesn’t have the records methods (like getPK)
but for getting a dataprovider value it works the same as a record.
Armin_kessler:
Kahuna is in Right.
Kahuna is always right and we are looking forward to the Cookbook he promised 7 months ago! Happy to review it.
Jan Aleman:
Armin_kessler:
Kahuna is in Right.Kahuna is always right and we are looking forward to the Cookbook he promised 7 months ago! Happy to review it.
- nice one Jan - very petty of course - and I’m surprised you’ve slipped so far from your usual professional! response.
But, and its a big one - point taken. we did say we were going to develop the cookbook and likely still will. For those interested the wind was kinda taken out of our sails when we had so much feed back on how it should be on some other site and we should not create a new home for it. To be frank, we’ve had so many difficulties with our Servoy development, learning on the fly so to speak, that the cookbook has taken a back seat. We are almost there with our roll-out though so in a couple of months we’ll have the opportunity to think again.
For us at least, Servoy has been a huge learning curve - primarily because of the lack of documentation. To be honest, the more we learn about the tools the less we are confident in a cookbook issue purely because there are so many gotcha’s and areas where we don’t understand the how, why or the potential of it.
So in summary you are right Jan, we missed our target, and realised that you have us beat! Without your documentation we’ll continue to struggle on I guess, possibly until we can afford the luxury of porting to some other environment, or get good at deciphering your cryptic offerings of developer support. And in the mean time we wont be impinging our own home spun view on other developers - so I guess we’ll see if there is anything we feel is of value we can contribute in a cookbook in the future.
Mean time - since you are all stretched for time - how about Servoy commissioning some of our more learned brothers to develop some ‘How To’s’ and proper developer documentation - perhaps around the sample solutions.
Maybe then I’d be a little bit right… well… partially right… ahh perhaps we’d all be right because we’d all be able to achieve the true potential of Servoy some time soon!
Kahuna:
Mean time - since you are all stretched for time - how about Servoy commissioning some of our more learned brothers to develop some ‘How To’s’ and proper developer documentation - perhaps around the sample solutions.
This is already in progress, more on this soon.
Jan:
CookBook, Tutorials, Documentation is not your work ??? , Do you remember
that you tell me that you are working in Tutorials and Doc. one year ago,
or the Documetation and tutorials is for Servoy 6 ???
If your are looking for training videos, there is a large selection (over 10 hours worth and growing!) of Servoy tutorial videos: http://www.servoyuniversity.com
I am running behind on creating the certification exam, however the videos are all there, and we will be adding more.
Having come to Servoy 2.1 from Filemaker with no Javascript and precious little actual coding experience I can vouch for the fact that good documentation would have made life easier. However what is good documentation ? who should be responsible for creating it ? at what level ? and what alternatives are there ? As my experience has developed so have my needs from the docs so what suits now would have been very different on day one.
Servoy as a company have more than delivered on many levels, specifically direct email help, answers to questions on the forum, various training video’s, white papers and documentation. Sometimes this has not met my needs, either its been too complex, in as in the case of the Wiki incomplete, but for the most part I have got served when I needed it most. I have also purchased support packs from Servoy and had excellent 121 help direct from Jan Aleman, Paul Bakker and Maarten Berkenbosch. In every case Servoy has more than made up for the lack of documentation when it has not been available or at a level I could understand. Ultimately Servoy is a fraction of the size of Microsoft/Adobe et al, punching well above its weight and for the most part doing an excellent job both developing, selling and supporting its products. Like so many in the same position the docs lag the development and for the most part that is just life.
The forum is a great resource, but can be limited and does tend to wander off message. It is a discussion forum not a documentation/examples resource. There is rightly no clear road map for contributions and due to its own success it has become a vast database of information which is hard to research even with Google.
Wikipedia for Servoy ? Is it time for the community to step up and produce a Wiki ourselves ? How realistic is it for a developer to write a Cookbook for Servoy with other pressures like “WORK” getting in the way!! I personally would not have the time, but I certainly could contribute the odd article and example to specific subject requests. I believe that as a group of developers our success is very much based on the the success of Servoy. ALL major applications have copious books and resources written for them by the community - take Cold Fusion or .Net as an example. What would directly help developers NOW and Servoy and the community would be a set of well written, edited and checked examples that we can all work from or contribute to.
Whilst its tempting to get into “discussions” and “finger pointing” on the forum, what I believe we really need is a solution that works for all and the easiest way to achieve this is to for everyone to work together.