Wiki improvements

Forum for discussion about the documentation project.
Post Reply
Carlos Herrera
Posts: 82
Joined: Nov 28, 2011 13:29
Location: Dictatorship

Re: Wiki improvements

Post by Carlos Herrera »

sancho3 wrote: A Brief Introduction To Trigonometry No problems.
The tutorial does not clearly explain important differences between ATAN and ATAN2 functions
(first returns angles in (-pi/2,+pi/2] interval whereas second outputs values in the (-pi,+pi] range, ...).
sancho3
Posts: 358
Joined: Sep 30, 2017 3:22

Re: Wiki improvements

Post by sancho3 »

@Carlos
I will add the line as you wrote it.

It is titled "a brief intro...". and it is half a page long. There are many aspects of trig. it is not explaining.
I recommend that if you are comfortable with trig., write an expanded tutorial to replace this very short one. But remember that this isn't a Math Wiki, so try keep everything relevant to FB or at least programming in general.
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Post by MrSwiss »

Updated: C/C++ vs. FreeBASIC syntax comparison

The previously used: Integer (only correct with 32 bit compiler)

Replaced with: Long (correct with both compiler's 32/64 bit's)
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Post by MrSwiss »

Updated: https://www.freebasic.net/wiki/wikka.php?wakka=ExtLibcairo

Changed: SizeOf(Integer) to SizeOf(ULong) -- for 32/64bit compatibility
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

@admin,
Have you noticed my discussion with paul doe (inside the Dictionary Class thread), that I summarize below:
paul doe wrote:Many thanks to fxm for this wonderful thread:
How to manage a critical section of code of a thread in FB
fxm wrote:Happy that this thread finally seems to serve someone :-)
paul doe wrote:I used it as a reference, so perhaps it'll be better served in the FB Wiki, no? Things posted here in the forum have a tendency to get buried very soon, and there are some things one should rather not forget, or have something to be used as a quick reference without having to skim through a lot of info...
fxm wrote:I think this kind of thread goes beyond the classic tutorial, and that it would find better place in rather the "Programmer's Guide" but creating in my opinion a new topic which would be for example "Advanced programming techniques" where experienced users could record their own knowledge in their favorite areas. I could probably myself add other topics such as "Dynamic allocation of memory", "Advanced UDT (with constructors / operators / destructor)", "Inheritance and polymorphism", ...
But it's already a lot of work to write such threads in the forum that it would be even more in the documentation, because having in addition to respect the formatting of the pages and if possible in a good English concise and precise at the same time.
And maybe all this work will interest only a few other users?
paul doe wrote:Yeah, I understand how you feel. However, in their transition to a more evolved state of know-how, some FB users will invariably start to look for this kind of information, so it could also prove invaluable for the future of FB. Right now, we are doomed to address the same issues over and over again, in a cyclic basis, because there's not a centralized 'hub' where one could look at the needed info in an indexed way. So, we dump things here, perhaps one day somebody will find an use for them ;)
fxm wrote:Administrators, perhaps we could first move these such threads (that have a pedagogic vocation) to the documentation forum, and by ensuring that their titles contain relevant key words for an easy search.
  • These threads could be pinned to the top of the list (as others presently)
Any echo from you would be welcome :-)
coderJeff
Site Admin
Posts: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

OK, moved to Documentation Forum and made sticky.
fxm, let's try it out.
- If a number of topics like this are identified and moved here, I suggest making one sticky (pinned) topic that links to the individual topics.
- What are the expectations for topic naming and content? The forum search allows searching a specific forum.
- For quality topics, I will guess you have some expectations in mind for posting. Maybe for pruning out unrelated comments or discussion too?
paul doe
Moderator
Posts: 1730
Joined: Jul 25, 2017 17:22
Location: Argentina

Re: Wiki improvements

Post by paul doe »

coderJeff wrote:OK, moved to Documentation Forum and made sticky.
fxm, let's try it out.
- If a number of topics like this are identified and moved here, I suggest making one sticky (pinned) topic that links to the individual topics.
That's a great idea =D
coderJeff wrote: - What are the expectations for topic naming and content? The forum search allows searching a specific forum.
May I suggest something? Perhaps something like 'Tutorial: Managing a critical section of code in FreeBasic?' Or something along the lines. 'Reference:' could also be used, I think...
coderJeff wrote:- For quality topics, I will guess you have some expectations in mind for posting. Maybe for pruning out unrelated comments or discussion too?
Is it possible for fxm to moderate the Documentation forum? That way, he could perform the curation of the content there. Just some random suggestions =D
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

I think that in general the other users are more able than the author himself to judge the relevance of putting a topic in the Documentation forum for these pedagogical qualities.
As a first step, I therefore invite all users to propose here already existing topics to be promoted in this Documentation forum (by providing the references of the topics to transfer to the Documentation forum).
It is obvious that it will be necessary most of time to do some cleaning work to make the retained topics more compatible with user documentation.

Note: If we need to prune the original topic (and delete a few / several posts) to put it in the form of documentation, is not it better to make a copy of the subject and not a transfer (no loss of information whatever is and respect of the original participants)?
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Post by MrSwiss »

fxm wrote:Note: If we need to prune the original topic (and delete a few / several posts) to put it in the form of documentation, is not it better to make a copy of the subject and not a transfer (no loss of information whatever is and respect of the original participants)?
This seems to me, to be a very important step. I'd additionally propose
to add a back-link, to the original thread, since some might prefer the
'un-pruned' version. (Otherwise, if the original was, in any case/way
compromized, I'd oppose the *whole* issue/idea!)


Reason:
Exactly their case might have been 'pruned' (because of: not being 100%
'on topic'!).
coderJeff
Site Admin
Posts: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

The goal is to deliver teaching content to users. That's a good goal.

Proposed solution is to highlight tutorial/teaching/pedagogic articles on documentation forum. I am willing to help this idea evolve, provided members have the understanding that it probably won't be perfect process first time and for all time. (fxm, you have cared about FreeBASIC and contributed to documentation for years and years and I would be pleased to support you and to work together with you on this)

The forum (reference topic or article topic) has benefit of good initial content delivery, good opportunity for discussion, but is not good for long term reference or document version control, and has potential for unrelated content, if not moderated.

The wiki (tutorial page or programmer's guide page) has the benefit of good document version control, stored in the main repo, and can be delivered to off-line formats, but is not good for topic discussion.

Both wiki and forum have potential to eventually become out of date due to new developments in the FreeBASIC project. And the search engines for both are not great, and can give unhelpful results, due the volume of information.

I want to share a few thoughts about each:
Board:
1) Board is very lightly moderated. There have been a few exceptions.
2) Each forum tends to dictate the general subject of the opening post, but after that, it seems anything goes, and all manner of discussion follows.
3) Some members have this expectation that the forum is to be a transcript of their every thought. Endless quoting to serve as evidence for the lawyer like battle to follow.

Wiki:
4) New pages are rarely added, and usually only by developers.
5) No new tutorials added in ages, though they could be.
6) Tutorials tend to remain untouched, even though original author has lost interest or moved on from fb.

Potential process is:
- original topic (or topics) in some forum
- indexed and moderated topic in documentation forum
- conversion to wiki page (does not need to be original author)

Overall, a good goal. How to achieve without adding too much burden/grief for admins/moderators/developers?
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

I see that the collective euphoria of January to improve the documentation has dropped like a cheese soufflé when right out of the oven. Many people to chat but almost no one now to achieve concrete things.
It's why I do not propose miraculous things (that may be why there is little reaction), but me at least all I already proposed or still propose, I will surely do it if it's accepted by the FB community.
coderJeff
Site Admin
Posts: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

fxm, sounds reasonable to me, let's see what happens. I've added you as moderator for the documentation forum so we can work together on this. Thank-you!
paul doe
Moderator
Posts: 1730
Joined: Jul 25, 2017 17:22
Location: Argentina

Re: Wiki improvements

Post by paul doe »

fxm wrote:I see that the collective euphoria of January to improve the documentation has dropped like a cheese soufflé when right out of the oven. Many people to chat but almost no one now to achieve concrete things.
Give it a little more time, it's just too flamant right now. I think that, in time, many people will contribute (I certainly will =D)
fxm wrote:It's why I do not propose miraculous things (that may be why there is little reaction), but me at least all I already proposed or still propose, I will surely do it if it's accepted by the FB community.
Accepted and well deserved, too. Congratulations on your promotion to moderator of the Documentation forum =D
Last edited by paul doe on May 10, 2018 16:17, edited 2 times in total.
paul doe
Moderator
Posts: 1730
Joined: Jul 25, 2017 17:22
Location: Argentina

Re: Wiki improvements

Post by paul doe »

Some more random suggestions (sorry if they're a little naive):
fxm wrote:I think that in general the other users are more able than the author himself to judge the relevance of putting a topic in the Documentation forum for these pedagogical qualities.
Can the 'report post' function of the forum be used for this purpose? I mean, it allows one to state the reason for the report, so it can also be used to 'report' a useful/insightful post/thread to be added to the Documentation forum, no?
coderJeff wrote:...Overall, a good goal. How to achieve without adding too much burden/grief for admins/moderators/developers?
It just turns out that a fellow countryman of fxm already coded something that could be used to aid mods/admins on this task: viewtopic.php?t=24922#p222923. He used it to index the 'Tips and Tricks' section, but I imagine it can be used to index also the Documentation forum ;)

About the indexing: the index could be a sticky topic, that contains the index of the Documentation forum built with the tool mentioned above. And in the Documentation forum itself, the relevant threads are kept separated as usual (to allow discussions/clarifications/modifications), and tagged if it needs be (we can agree on a limited number of them, for ease and consistency). The index can also be used to browse over interesting content, much as I use the post by Tourist Trap right now...

@coderJeff: thank you for your prompt assistance on my little issue.
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

I'm wondering about the well-identified bugs (by bug reports), but for which the fix output seems to be postponed or even never to happen:
Should we then add a note in the relevant page(s) of the documentation for the bugs most likely to be encountered by the user ?
(this has already been done, but for a very small number of cases)
Post Reply