Morley:
bcusick:
It is not realistic to expect:
a) Every single thing you’re confused on to be in the documentation;
b) Every single possible permutation of every possible method or circumstance you come across while developing your solution to be documented;
c) That the doc team can read your mind on how you think about items - and then index it that way
Our documentation is a REFERENCE guide - NOT a training manual. If you have a better index - please email it to me at bcusick@servoy.com and I will pass it on to the documentation people.
Sorry… I just had to vent on that one.
With great respect I must vent right back. That’s an extreme and defensive statement, NOT one I hold. Documentation is not tutorials and should not be.
My comments have to do with indexing. In each of Servoy’s manuals the index amounts to just a few pages. Good documentation has extensive cross referencing of all major terms. For reference I point to O’Reilly’s JavaScript, the definitive guide with more than 70 pages to its index clearly organized with great energy and care.
“Calendar” does not appear in either of Servoy’s developer manual indexes. Likewise many other significant terms. They’re just not there. If you like I’ll start a list of what’s not there.
For access Servoy’s documentation primarily relies on the table of contents. To be effective, documentation should have access from a number of directions. Indexes are particularly useful when the user is looking for a term which may turn up in a number of different places and contexts and/or the user is not yet familiar with how the material is organized. Indexes, good ones, are not an after thought. I repeat, in more polite language, Servoy’s indexing is inadequate to efficient use of its documentation. This man’s experience and opinion.
So as to ward off flame wars, I should say I like everything about Servoy and the Servoy team with the sole exception of documentation. I feel liberated by Servoy and am immensely proud of what I’ve been able to achieve using Servoy over the past six months. That’s a testament to the clarity of thought that’s gone into the creation of Servoy, not to my stumbling efforts. Servoy is very important to me, sufficiently important to point out a glaring (IMHO) weakness.
Servoy’s hundreds of pages of documentation should be easily searchable, which in its present condition, for whatever reason, it is not.
Kind regards,
Morley,
Your points about Servoy documentation are well taken. While your
frustrations with the limitations of Servoy documentation may be shared,
general venting does not help to improve the quality of that information.
However, to clarify some of the issues that you raised:
-
Indexing, to the degree (as in number of cross-references and pages)
that you mention in your post, requires hundreds of hours (in some cases,
thousands of hours). While we are certainly interested in providing a
useful indexing scheme in the Servoy books, the priority for the time
spent producing these books is making sure that the hundreds of
screenshots, descriptions and examples for all the features and
functionality that Servoy includes are constantly updated based on
released Servoy versions.
-
Indexing for commercially available books such as the one that you
mentioned in your post are separately funded - in many cases, the
publisher requires the author to pay for the cost of indexing. For Servoy,
this would mean that if there are developers that wish to financially
contribute so that more complete indexing moves up the feature request
list, we will be happy to consider those requests.
-
The tools that are used to produce Servoy’s documentation are
single-source. The advantage of using such tools is that we can
simultaneously develop the same information for the online Servoy Help
Navigator for all of Servoy’s product line, as well as the printed Servoy
books and corresponding pdf files.
Much of the printed documentation that is currently available for software
applications today cuts way back on content and instead heavily refers
(and in certain cases, forces) the reader to use an online help system.
The disadvantage is that unlike a program such as MS Word, where you
can specify any word or phrase as an indexed item, these tools index
topics (rather than single words or paragraphs) by default - this being the
reason that there is a great deal of similarity between the topics in the
Table of Contents and the items listed in the Index of Servoy books..
All other instances of index items must be manually entered and manually
referenced to relevant topics - one at a time.
-
With regard to finding information about “calendar”:
We appreciate your suggestion to include “calendar” as an index item in
the printed Servoy books, and will update the next version of
documentation accordingly.
-
While it is true that there is no index item in the printed Servoy books,
and it is also true that there is no index item that can be found in the
Servoy Help Navigator, you CAN select the “Search” tab in the online
Servoy Help Navigator and enter “calendar”. This will show two topics that
include the term and/or function related to calendar.
Once you have opened the desired topic (double-click on the topic from
the topics list at the bottom of the “Search” tab), choose Tools>Find and
enter “calendar” in the “Find What” criteria to highlight the first instance of
“calendar” in the opened topic. Press the “Find Next” button to search for
and highlight each additional instance of the word “calendar” in the
opened topic.
It is our intent to provide documentation as a useful tool in the process of
developing Servoy solutions and applications.
If you have one or more specific items that you feel would be beneficial to
include in one or more of the Servoy book indexes, you are welcome to
email me directly at mnorman@servoy.com with the index items and the
Servoy book that the index items apply to.
Marc Norman
Servoy