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

[PICCORO McKAY Lenz]

El sáb, 29 de may. de 2021 a la(s) 15:34, Bruce (adamnt42 at gmail.com)
escribió:

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

i will read complete mail.. but this IS CORRECT! *The Gambas wiki is one of
the best structured, elegant and  sensible online help sites anywhere!* i
hate the gambas benoit markdown sintax .. (tables are ilegible in source
mode, and marks are special.. but best usefully for ) but that work of
gambas wiki is the best wiki! good work Benoit and all of you guys!


> 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.
>
> ----[ http://gambaswiki.org/wiki/doc/netiquette ]----
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.gambas-basic.org/pipermail/user/attachments/20210601/8f3c7544/attachment.htm>