Documentation Updates -When???

Classic Servoy
1

In Feb this year, at the Servoy Developers meeting at Sun House in London, Jan Aleman stated that there were moves afoot to produce up to date documentation for Servoy. Since then we’ve had two new release’s of the software and a sample docs-wiki published. But no updated documentation.

When can we expect new and up to date documentation, and when it arrives is Servoy intending to cover everything (including samples of using the beans and plugins)?

Not sure how others feel about this (though it seemed every developer at that meeting was in agreement about the need for it) but I think its very urgent!

This message was prompted by Jan’s webinar (sales promotion!) last night on .NET. One thing he didn’t mention was that .NET documentation is second to none (both MS stuff and third party publications), yet Servoy has such poor documentation that the only way to discover how a lot of Servoy works is by searching and asking questions on the Forum! I’ll wager that if many of those developers asking questions last night knew about the poor standard of documentation they would run a mile rather than cross over to Servoy. Similarly Jan indicated that a skilled VB developer could become a specialist in Servoy in a MONTH!!! Without documentation I doubt that very much (at least outside of the rarefied atmosphere of the ISV Programme with in-house training).

Could Servoyians please give us some guidelines on publication dates?

EDIT: Hope this wasn’t taken as a rant as that wasn’t intended. Jan and the Guys in Servoy do fantastic stuff for us - but unfortunately some of it falls short simply because we cant discover how to use it effectively and quickly! Please let us have some new documentation Jan!

2

Kahuna:
In Feb this year, at the Servoy Developers meeting at Sun House in London, Jan Aleman stated that there were moves afoot to produce up to date documentation for Servoy. Since then we’ve had two new release’s of the software and a sample docs-wiki published. But no updated documentation.

When can we expect new and up to date documentation, and when it arrives is Servoy intending to cover everything (including samples of using the beans and plugins)?

Not sure how others feel about this (though it seemed every developer at that meeting was in agreement about the need for it) but I think its very urgent!

This message was prompted by Jan’s webinar (sales promotion!) last night on .NET. One thing he didn’t mention was that .NET documentation is second to none (both MS stuff and third party publications), yet Servoy has such poor documentation that the only way to discover how a lot of Servoy works is by searching and asking questions on the Forum! I’ll wager that if many of those developers asking questions last night knew about the poor standard of documentation they would run a mile rather than cross over to Servoy. Similarly Jan indicated that a skilled VB developer could become a specialist in Servoy in a MONTH!!! Without documentation I doubt that very much (at least outside of the rarefied atmosphere of the ISV Programme with in-house training).

Could Servoyians please give us some guidelines on publication dates?

EDIT: Hope this wasn’t taken as a rant as that wasn’t intended. Jan and the Guys in Servoy do fantastic stuff for us - but unfortunately some of it falls short simply because we cant discover how to use it effectively and quickly! Please let us have some new documentation Jan!

I did not talk about .Net documentation at all during my webinar so I’m not sure where that point comes from. You are correct that in the London seminar earlier this year I mentioned we are switching to a new documentation system which will allow us to publish more data more frequently. We are in the final stages of finishing and testing that system before it can go in production. Once it is live it is going to be easier to send in feedback and/or to contribute to the documentation.

Meanwhile you can always ask your questions here in the forum. And if you need advanced help there are many companies out there that you can readily hire. You like comparing it to the Microsoft world: I have developed in many Microsoft technologies in my life and have found it impossible to do so without either external support or third party documentation. In contrary to this we do have the goal to provide more complete documentation but it takes time.

I personally know multiple VB developers that were specialist in Servoy in less than a month, and they did use the standard documentation, not the ‘without’ documentation version you suggest.

3

Jan Aleman:
I did not talk about .Net documentation at all during my webinar so I’m not sure where that point comes from.

That’s really one of my points Jan - you like to compare Servoy / .NET but when asked about documentation it seems its not a relevant comparison. How many developers do you believe would be happy to make the cross over if they know ahead of the game that they will need to develop a lot of the Servoy model blind or use the forum to figure out how things work. .NET documentation is excellent and I too have been developing in MS technologies for many years - so the comparison is appropriate.

Jan Aleman:
You like comparing it to the Microsoft world:

No Jan, you like to make that comparison, I’m simply following your direction!

Jan Aleman:
Meanwhile you can always ask your questions here in the forum. And if you need advanced help there are many companies out there that you can readily hire.

As I explained in our private email correspondence Jan, I already have invested thousands of pounds in just that, and will continue to do so. It seems that you are happy with this situation - if I need to figure out how a specific aspect of Servoy works - which is undocumented - I should hire someone else (despite us being very experienced developers ourselves) to figure it out for me or ask on the forum?

Is that really a professional approach Jan?

Jan Aleman:
I personally know multiple VB developers that were specialist in Servoy in less than a month

I have met some VERY exceptional developers in my time (I deployed my first app to Oil & Gas clients in 1987) many who would make me look like a typewriter in comparison to their ‘deep blue’, so I dont doubt some could do this Jan - but where did they get the information to become specialists - its not in the docs?

I readily understand VB developers grasping the basics - but becoming specialists?

You’ve suggested, elsewhere Jan, that I am looking for ‘freebie’ support, that’s absolutely untrue - and hopefully one of your own Servoy colleagues will confirm that fact to you! I’m simply looking for sensible and sufficient documentation - as befits a paid for RAD tool.

Jan Aleman:
In contrary to this we do have the goal to provide more complete documentation but it takes time.

That’s fantastic to hear Jan - I really so want our apps to be the best they can be in Servoy, and to do that I need this documentation.

Do you have a likely delivery for these?

That’s all I was really asking in the first place, though it seems my frustration is showing through!

4

You make it sound as if no documentation exists currently for the Servoy platform. As with all documentation there is room for improvement and as I have now stated multiple times that is exactly what we are doing based on the constructive input we are getting. We expect the first version of the new platform to go live soon. Meanwhile if you have particular questions you can post them here on the forum. Can you provide examples of plugins you find poorly documented?

5

Jan Aleman:
You make it sound as if no documentation exists currently for the Servoy platform. As with all documentation there is room for improvement and as I have now stated multiple times that is exactly what we are doing based on the constructive input we are getting. We expect the first version of the new platform to go live soon. Meanwhile if you have particular questions you can post them here on the forum. Can you provide examples of plugins you find poorly documented?

Hi Jan,

you will say that some plugins have sources inside, which is true (and I did rely on them a lot to get a grasp on how to do things), but still there is little to no javadocs in theses sources and the javadocs API has almost nothing in terms of comments. So when you want examples of poorly documented plugins, I would say “all of them”.
I do think that it is one array which desperately needs your attention.

We all know that documentation takes time to do and keep up to date, and I do realize that you are making the best you can to keep the pace with each Servoy’s release which are the fastest that ever been in the IT world to my knowledge!
But maybe you could slow down these releases a little to concentrate on the docs?
I do hope the new platform will help with keeping things up to date, and I’m sure every fellow developers will contribute in time to help with it, as they already do in the forum.

Ian has a point here in saying that the matter is urgent if you want to attract a more wider audience. I would say too that this audience will first be coming from the Java community, but I know that these people are used to a wealth of documentation that is not existent right now for the Servoy platform.

The documentation should always go on par with the product, not be added as an afterthought.
Now if I say these things, once again be sure to take is as positive, because I do love the platform and think it is rich and clever, and I would like other people to jump into it, just as I’m sure you do!

Sincerely,

6

Another debatable topic:
I for one am glad that priority is placed on getting out feature upgrades in advance of the [adequate] documentation.
Having the forum as backup no matter what the latest scheme is for documentation delivery is a good strategy and one fairly inexpensive, although, admittedly perhaps not timely on occasions.

So I will welcome another documentation delivery scheme and the chance to “participate” in the user updating.

7

Thomas Parry:
Another debatable topic

That’s why we debate it ;-)

Seriously, yes, the rate at which Servoy has been improving the software is really incredible, there’s really no doubt about it!
But even though bug fixes sshould always be priority number one IMO, the next top priority should be the docs, not implementing new features unless they are fully documented as well.

I’m glad of the next Tano beta coming soon, and I enrolled to beta test it, but still I think that when this one will go live, the documentation should be in place reflecting precisely any changes/improvements/deprecated features/new features/bug fixes introduced with it, with full examples.

In any case if the current features were clearer to everyone and in a centralized, searchable and up to date place, that would also give more time to Servoy’s engineer (who spend a significant amount of their valuable time re-explaining the same feature again and again in the forum) to implement these new features everyone is always eager to have. I’m not saying this is wrong of them to reply, of course!
I’m just saying that there might be less questions for them if everything was clearly documented already.

8

As Jan already mentioned, we are in the process of finalizing a Wiki like documentation system, where others can participate.

The goal is, like Patrick asks for, to deliver up to date documentation with the final release of Tano.

Paul

9

pbakker:
As Jan already mentioned, we are in the process of finalizing a Wiki like documentation system, where others can participate.

The goal is, like Patrick asks for, to deliver up to date documentation with the final release of Tano.

Paul

That’s great news Paul - do you have a planned date for when that documentation and Tano will be available?

10

We all like Servoy – the company and specially the product. This debate is proof of that. Still there are areas of improvement –in particular in documentation. Certainly, you can build an application in Servoy without much documentation. The first time I used Servoy I built a full custom application in one week –that was a couple of years ago. However, after reading thousand of pages of documentation, I had more questions than answers, but I really didn’t have the time to post them here on the forum.

At the present, java developers need javadocs for the plugins’ sources. 4GL and FileMaker developers need more “how to do” recipes in the area of scripting for servoy.

The issue of the javadocs has been appealed by Patrick and others. I entirely concur with them.

About the former 4GL and FileMaker developer: I would suggest an update of the “Servoy Advanced Programming Guide for FileMaker Developers” – more specifically, this document should include all of the current FileMaker Scripts against their equivalent methods or “How-To-Dos” in Servoy. This document will be very much “appreciated” by the companies that are moving from FileMaker to Servoy. In addition, this new document should have in mind all of the former 4GL developers and not just FileMaker developers.

I appreciate the effort that Servoy management is putting into this. I look forward for the Wiki like documentation system, where many can participate. We still need the javadocs for the plugins’ sources and a “Servoy Advanced Programming Guide for FileMaker and Former 4GL Developers.” Is the Wiki going to have room for this?

11

I have to agree with the docs issue and this is not a rant, more constructive critisism. The learning curve for Servoy is steeper than it should be, because of a lack of any good centralised education tool, like a ‘Head First’ book or something. Learning Servoy to me was like climbing into the cockpit of a Jumbo jet and trying to fly it. So many controls, concepts and gotchas; it would have been so much quicker with really good docs. After take off, you quickly find yourself in ‘how do I do set up for landing’ (or ‘How do I place a related form on a tabpanel, hide the tabs and show/hide programatically’?)

I recently learned the basics of Java and I found it much, much easier than Servoy. Reading a book on Java and trying and testing code made me feel clever; stumbling along with Servoy makes me feel stupid!

The forum is great, I am always very appreciative and grateful of the assitance I get, however it would be good to have all the info in an easy to reach place. The tutorials in the developers area are good too, but it is a case of not knowing what you don’t know. For example, the solution model - who would know what that does? Excuse me if I am wrong, but there seems to be nothing in the Servoy help, no online tutorials.

This is a great product, I am sometimes amazed by what it can do, especially if you tried all the GUI stuff in Java - you’d take 10 times as long playing around with JFrames, JButtons, JMenu items etc. .NET? Only if I had to, but the docs are there. I think Servoy could be adapted by more developers if the educational material was available, addressing this should be an urgent priority IMHO. This product has so much going for it - it deserves better than the current docs.

12

Although this isn’t the answer to better documentation for Servoy proper, I do want to at least point out that certain community members have been working hard to provide developers with better documentation for some time now.

As one simple example…perhaps Servoy can lean on the efforts of the community a bit here and replace pages such as:

http://www.servoy.com/generic.jsp?mt=39 … omy_id=571

With pages such as:

http://java-servoy.blogspot.com (Where Patrick Talbot has posted excellent, in-dept information about how to write plugins and beans).

I know that there seems to be a move to a collaborative doc tool/site, and that sounds great, but there are certain sources of better documentation available already. Why not use them/link to them and support the efforts of the community!? (as opposed to working in a vacuum)

13

jbader:
Although this isn’t the answer to better documentation for Servoy proper, I do want to at least point out that certain community members have been working hard to provide developers with better documentation for some time now.

As one simple example…perhaps Servoy can lean on the efforts of the community a bit here and replace pages such as:

http://www.servoy.com/generic.jsp?mt=39 … omy_id=571

With pages such as:

http://java-servoy.blogspot.com (Where Patrick Talbot has posted excellent, in-dept information about how to write plugins and beans).

I know that there seems to be a move to a collaborative doc tool/site, and that sounds great, but there are certain sources of better documentation available already. Why not use them/link to them and support the efforts of the community!? (as opposed to working in a vacuum)

Jeff I agree with you. In fact we have been linking to the website you mention for over a year now (under third party publications) and your suggestion to link to it from the pages mentioned is an excellent one, I’ll forward it to our webmaster.

Having developed for many years in Turbo Pascal, various Microsoft languages, Oracle and Java I have always used third party documentation to learn the tool. For a vendor it is very difficult to come up with one set of reference manuals that satisfies everybody: nevertheless we try to make our documentation as broad as possible to offer help to as many developers as possible. Currently we offer over 2000 pages of documentation and nearly 100 tutorials and howto’s and yes we continue to extend them as well, if you send in feedback please be specific, in this thread many posters only say they miss something without saying what they exactly miss.

Last but not least a big applause for all those third parties (eg Jeff, ptalbot, etc, etc) who actively write great articles and howto’s!

14

Jan Aleman:
Last but not least a big applause for all those third parties (eg Jeff, ptalbot, etc, etc) who actively write great articles and howto’s!

+1000% Jan.

Additionally all those from Servoy (past and present) who have supported the forum with tutorials, help and just plain sensible advice too - and in my case - responses to dumb questions (though I guess at the time were only dumb in the circumstance of not having full documentation)!

The forum is brilliant - bring on the documentation!

15

Kahuna:

Jan Aleman:
Last but not least a big applause for all those third parties (eg Jeff, ptalbot, etc, etc) who actively write great articles and howto’s!

+1000% Jan.

Additionally all those from Servoy (past and present) who have supported the forum with tutorials, help and just plain sensible advice too - and in my case - responses to dumb questions (though I guess at the time were only dumb in the circumstance of not having full documentation)!

The forum is brilliant - bring on the documentation!

And looking forward to examples how you think the documentation can be improved, please be as detailed as possible.

16

Jan Aleman:
[

And looking forward to examples how you think the documentation can be improved, please be as detailed as possible.

It would be great if you could host a list somewhere on Servoy.com Jan, where we could add documentation item requests! Would that be possible?

There, folks could see what’s already been requested and expand or add to it. Otherwise I guess it would just become a really long forum post with disjointed requests!

Also, there are a number of points raised on the Forum (with great answers and in many cases with examples), could these be adapted into the Wiki Docs?

Thinking along those lines - there are loads of Forum Posts that could be directly converted into FAQ. I’m thinking particularly of responses that are examples and how too’s. I reckon if these were in a FAQ format they could really support the documentation already in place - and perhaps later become part of the Wiki!

17

jbader:
Although this isn’t the answer to better documentation for Servoy proper, I do want to at least point out that certain community members have been working hard to provide developers with better documentation for some time now.

As one simple example…perhaps Servoy can lean on the efforts of the community a bit here and replace pages such as:

http://www.servoy.com/generic.jsp?mt=39 … omy_id=571

With pages such as:

http://java-servoy.blogspot.com (Where Patrick Talbot has posted excellent, in-dept information about how to write plugins and beans).

I know that there seems to be a move to a collaborative doc tool/site, and that sounds great, but there are certain sources of better documentation available already. Why not use them/link to them and support the efforts of the community!? (as opposed to working in a vacuum)

Jeff following your suggestion Marc, our webmaster (amongst others), has updated our website accordingly:

http://www.servoy.com/generic.jsp?taxonomy_id=571

18

Jan,

Thank you for acknowledging the efforts that have been poured into the blog and into the documentation that the community has made available on the blog. Much appreciated, and I am sure that anyone who is searching for comprehensive information about plugins or beans will find P. Talbot’s whitepapers most useful.

This is a great move. Looking forward to seeing more connectivity between Servoy and the Servoy community!

19

Hi Jan,

thanks for the links! I hope that these little articles will help:
1/Servoy developers understand how well (and easily) Java in Servoy can be used to build enhanced solutions and help build reusable components, and that
2/ it will also help Java developers to see how Servoy is a great Java RAD tool where they can leverage their own experience and components.

I would say that your next best move in terms of documentation enhancement would be to review the javadocs of the public API: example of usage of the interface in the header for each interface, along with example usage for each methods would really help a lot!

Since you are asking for precise examples: a simple one of something that could be clearer, and demands a lot more than one line of comment per method is the ICmdManager: What can you really do with it?

What’s an Action vs a Command? These are such highly abstracted concepts anyway that unless you place them in the context of their possible usage in Servoy a line such as

Servoy Public API:
The Action and Command manager.

descibing the ICmdManager interface is meaningless.

Thanks in advance for your attention on these crucial details,

20

I would love to see a Recipes book or site for Servoy.

Perhaps the community could pull together an official Recipes website from the many great articles that exist across several sites already. Start with the very basics, and progress through the most complex solutions, with code and explanation. Lots of great information is out there, but we don’t have a good, organized, central location for it. Let people submit recipes, then the community can comment and improve them. Mark them with complexity level, skill prerequisites, and key words. Doesn’t seem like it would be very complicated to setup.

Just some thoughts…

–Jason