[Gambas-user] The Wiki - Some [OPINION]
adamnt42 at gmail.com
Sat May 29 21:33:22 CEST 2021
Over the last 3 months or so there has been a considerable number of
posts that suggest something or other "ought to be in the help".
While these suggestions have been reasonable, I have some strong options
on what should go into the Wiki and more importantly where it should go.
Wiki authors should (IMO) keep the following in mind:
1) The multiplicity of places where a page can appear ---
a) in the help browser
b) in the small code completion popup in the IDE code editor
c) in the form designer Properties tab
d) externally in a web browser
2) The structure of the wiki ---
The Gambas wiki is one of the best structured, elegant and
sensible online help sites anywhere! If you want a comparison
with complexity, obscurity and mind-bending layout try reading
some of the TrollTech documentation at https://doc.qt.io/ ...
3) The structure of pages for syntax, explanations, "how-to's" etc ---
That list of page types is not unintentional. It follows the
"intent" of the sections on the start page. I will now talk
about some of my strongly held opinions regarding these.
This group includes the command syntax pages, the class overview pages,
component overview pages and language concepts pages. In other words,
the pages accessed through the Language Reference section of the start
page. The most important matter here is their appearance in the code
completion feature and in the IDE form designer.
These pages should be SHORT, SUCCINCT and conform to the unwritten
standard (which I shall now write).
These pages SHOULD NOT include LONG WINDED EXPLANATIONS of "why" or
"how" this syntax arose in Gambas.
NOR SHOULD they include LONG WINDED EXAMPLES. In fact sample code in
these pages should only be included when it can be IMMEDIATELY copied
and pasted into the reader's code.
They SHOULD (MUST) respect trademarks, copyrights, authorship's and
things of that ilk and should only contain external links where the
subject matter is perfectly and adequately explained on that external
page. A perfect example is Tobi's page on the Trie class in the gb.data
component where "You can learn about its semantics from Wikipedia."
Finally they SHOULD NEVER contain discussion about certain other
programming languages! The reader is looking for information on Gambas
programming, not programming in, say Fjölnir
There ARE places for these things, as discussed in the following.
These are the non-syntax pages in the Language Reference section.
These pages, IMO, are the exclusive domain of Benoit and should be left
to his authorship only.
"how-to's" and other documents
Now here (section 2 of the start page) is the place for most if not all
the guff that should be left out of section 1. The general rule is "go
for your life! The more the better". A really good example is the
"Network Programming" page by Daniel Campos and Benoît.
BUT some unwritten rules should be followed:
* Include an INDEX at the top. See the wiki manual for how to do that.
* DON'T waste space by repeating information that is adequately
explained elsewhere. Reference it and include a link.
* Observe the legal and professional courtesy rules mentioned above.
* (I'm sorry to have to mention this one, but...) If you have a less
than "almost perfect" ability to compose readable, correctly spelled
and grammatically correct English then SEEK ASSISTANCE before posting
the page. Probably the best approach is to draft the page in your
native tongue and seek help in translating it on the mailing list.
DO NOT rely on online translation services like Google(TM). The
results are often total gibberish. English is a hard language and
one where specific words have completely confusing meanings depending
on context and grammar. For example the word "BEFORE" has at least
three totally different and conflicting meanings.
* Freely use but dont over-use the "special boxes".
* (An odd one) Draft your pages or updates to pages in an external
editor until the draft is pretty-well up to scratch! At least get all
the content, spelling, grammar and structure sorted BEFORE (sic)
submitting the page into the wiki.
Pages in the other sections
In general DO NOT play with these pages unless you are a RECOGNIZED
EXPERT (in the Gambas world) on these subjects. Instead use the mailing
list to raise any ambiguities, suspected defects, etc etc.
RECOGNIZE that all the above is MY opinion and is NOT in any way an
"Official" policy of Gambas or it's author(s). The opinions are based
on well over 10 years of using Gambas. I think it was version 1.99?
Over that time I have had to repeatedly refer to the wiki because I
can't remember everything about the language ... ;-(
and finally, finally
To novice readers of the wiki pages, especially the first section pages
and the various popup helps. I just want to say (again) "Read EVERY
word of the help page." Every single word. When I first started with
Gambas I had to write that out and put it on the wall above my screen.
Whenever I got stumped, leaned back and saw that sign it jolted me into
re-reading the page to find the bit I had mis-understood. And beware, if
you don't do that and ask on the mailing list when the answer is there
in black and white you might incur the wrath of a certain old curmudgeon
who will impolitely tell you to RTFM! There is a reason for that and
it's not just intentional rudeness on my part. But that is a topic for
P.S. Feel free to discuss, disagree or otherwise comment on the above. I
welcome it, but will defend it until the keys on my keyboard crumble to
More information about the User