[Gambas-user] Gambas-Documentation

[Hans Lehmann]

A warm Hello to all friends of the Gambas programming language,

many years ago users complained in various Gambas forum posts about the
lack of books about Gambas in the German language. I liked Gambas from
the beginning. Its conception allows people, like myself, switching over
from other environments as well as ambitioned programmers to work on a
range of different tasks in a single language. This motivated me as early
as 2008 to design a concept for a Gambas book. For a few years now this
book is made available online at www.gambas-buch.de. Many chapters have
already been published. With great effort, the team of authors pursues
the goal to produce a good description of the components and classes of
Gambas and to demonstrate their use in example projects. Every chapter
and its parts are also offered as a PDF file, and archives of the tested
demonstration projects are available for download.

However, our work on the online book is hampered increasingly because some
components and their classes have only fragmentary documentation in the
Gambas wiki, or none at all. By tolerating this condition, the Gambas
developers throw away opportunities for newcomers to discover and use
Gambas. A class or component should, in my opinion, only be released after
its documentation is complete and correct and put on the Gambas wiki.
Do the developers really believe that a potential Gambas user will read
all the source code to understand how the properties, methods and events
work? (I, for one, have never learned C.) To me, for example, it is clear
after over 44 years as a grammar school teacher -- among others for
Computer Science -- that nothing motivates more than success und success
has to be prepared.

This brings us to the crucial point with Gambas: all efforts should 
currently
be directed towards quickly closing the gaps and flaws in the documentation!
One only learns a language well by speaking it -- and this is only possible
with a good dictionary! Such an excellent programming language as Gambas
should enjoy a thorough documentation of the existing components and classes
with small projects or code snippets which show the essential properties
and methods in action. If you have a look at the current state of the
documentation, you will see that it is exceedingly incomplete. Do the
developers seriously think that the Gambas programmers can read in a crystal
ball if all that's known about a class is the names of its properties,
methods and events?

The software farm with its projects does not replace a systematic treatment
of the basics of the language. The online book wanted to provide just that
for the German-speaking Gambas programmers, and those who want to be! If
none or only insufficient information about the properties, methods and
events of a Gambas class is available, then a newbie or a Gambas programmer,
who wants to use this class, will resign and turn to other languages.

My wish is essentially just that the developers do their job until the end
and provide the documentation for their classes, because only then can their
valuable work be truly useful. Only then can Gambas finally make progress.

Honsek
www.gambas-buch.de