[Gambas-user] Gambas-Documentation

Tue Jun 6 14:05:31 CEST 2017

2017-06-06 6:53 GMT-04:00 Hans Lehmann <hans at ...3219...>:

> 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.
>
the gambas buch its a great book, the problem its that its only in German..
many articles/chapers i read in that book, that-s why i made an effor this
weekend
and produce te lasted ODBC documentation examples in gambas wiki

that problem i anunce some oportunities before, but benoit mention that
made this only for hobie
its a great effort the components and languaje made by gambas developers..
for spanish users there's the jsbsan blog .. but hangs my web browser due
many anuncies

As hans mentions, prawns have evolved and is beyond simple pastime, many
projects i had to perform in php or java due to the urgency of having them
"fast", losing the opportunity to develop in this confortable and flexible
programing languaje called gambas ...

We are clear that the learning curve is fast and easy to program, but the
type of responses such as "it is the programmer's job" or assumes that "the
programmer must know how to program" distances the prospects, and does not
allow the development Of a business model Cost-effective based on low
maintenance and fast obtaining of manpowers

Currently taking the ODBC component as example, i note many lack of
documentation.. complete in this lasted days by me, the first ODBC
component documentation was very poor and inconsistent with the component
behaviour.. and as last, the compoent ntil version 3.8.1 was in very bad
state... and all the documentation assumed that all the features of the
mysql db componente are same for the rest.. and that's not true.. this
limit the gambas to a mysql database for novice users... due documentation
does not offer how to solve that situations...

> 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.
>
>
Hi hans, in this way, there's a problem.. many developers need the
component xyz due newer develop needs..

The real solution its that the documentation must be generated from the
component code.. like JAva does..

later then must be complete in the gambas wiki.. WITH EXAMPLES, i mean the
code documentations must not have example, only teoric implementations, and
later any enhanchement must be done in the generated gambas wiki page,
currently this behaviour seems are, but need more improvement...

> 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.
>

As i mention, We are clear that the learning curve is fast and easy to
program, but the type of responses such as "it is the programmer's job" or
assumes that "the programmer must know how to program" distances the
prospects, and does not allow the development Of a business model
Cost-effective based on low maintenance and fast obtaining of manpowers

Take a comparation of the today ODBC example documentation vs the old firts
ODBC documentation, or more easy.. lest compare the Mysql how to
documentatin vs the ODBC how to documentation>

http://gambaswiki.org/wiki/howto/odbcdatabase
http://gambaswiki.org/wiki/howto/database

>
> 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

umm.. gambas/buch need to be translated... its a good work but its only
german...

>
>
> ------------------------------------------------------------
> ------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Gambas-user mailing list
> Gambas-user at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/gambas-user
>