[Gambas-user] The Wiki - Some [OPINION]

[Bruce]

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.

"syntax" pages
--------------
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."
(link removed).

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 
(https://en.wikipedia.org/wiki/Fj%C3%B6lnir_(programming_language)) or 
something.

There ARE places for these things,  as discussed in the following.

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

Finally
=======
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 
another day.

best regards
bruce

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