Wiki Strategy

[Warfley]

Hi,

I was wondering, what the strategy for the maintainance and development of the Wiki is. Recently I've found this article: Developing Web Apps with Pascal, which has at least a misleading title, as what is written under Overview: "This page describes various ways of integrating javascript with Free Pascal." would imply that te contents "Integrating Javascript with FreePascal", but this seems to only be the case for the 2nd thing listed there, the first is an IDE for the already existing Pas2JS (which isn't linked there), and the last one is for building a backend with Pascal.
Also, all of these things seem to be outdated and haven't received any major updates in like 10 years.

This page was last Edited around 2 years ago, so someone looked at this and thought: "Oh yes this is good wiki page and a valuable resource for people searching for pascal web development".

Other things I've noticed where that some articles have seen heavy changes, like Installing Lazarus, which was reorganized into multiple sub pages, which is great, except that things got lost. E.g. previously it had instructions on how to build FPC using make, for example to build a cross compiler for Win64. Another thing that I am quite sure once was on there is the existance of the "lazarus.cfg", which now is nowhere to be found.
Both of these are quite important to the topic of installing Lazarus (and there seems to be completely an "installing fpc" page missing), so this effectively leads to knoweldge loss, as people who now seek this article can't learn about those things, and those that remember that there was something and want to look it up don't find it anymore.

Or multiple language pages is great, but sometimes the contents of the pages is not identical. E.g. For Compiler Directives the german and the english page have different contents. Most the other languages lack behind, but I have also seen that the german page actually had more information or was better structured than the english page.

Lastly there is a general issue I've found that it is often not easiely discernable if a page concerns something that is part of FPC/Lazarus or if it is a third party tool or software. Sometimes you find it just in the end of the Article when seeing that it links to a github or something like that.

As I've posted in another thread a few days ago, most developers learn through wikis, tutorials and documentation, much more than through books, school/uni/other courses. So I feel like that the wiki should be a high quality resource, and I would also like to participate to help with that.
That said, I feel like that there is currently no real strategy on how the maintainance is performed and lacking any standards or guidelines on how wiki pages should be created (otherwise I can't explain the existance of the article above).

So I would like to ask:
1. Is there a style guide for wiki articles, if not, maybe there should be one developed?
2. Whats the methodology for maintainance for existing wiki articles, because as I said before, with the Web Apps page, it seems to have failed?
3. How can people help?

If some volunteers could just pick a wiki page thats up for review and then look at it with a given style guide, I think many could put a few minutes a day into this, and with just a few volunteers in a structured way the wiki could be cleaned up and maintained quite efficiently.

PS: Don't get me started on Categories, they are a whole different mess (e.g. look at Main or AllCtg categories), but as I think no one is seriously using them to navigate the wiki I think they are the least of the problems

[Martin_fr]

Well, other than common sense, and don't vandalize... I am not aware of any guides or anything.

- There are a few "portal" pages and IMHO they are generally a good idea.
- Other languages are indeed often way behind.
- Some of the template (language bar, auto category, ...) afaik no docs on them either.

Issue is, just putting some guideline in place wont do much. Many people will never read it, often because they did not even discover it exist.
Though I wouldn't mind the attempt, if someone wants to give it a try. Yet, more in the sense of a "collection of suggestions", i.e. not a "should be done  in <whatever> manner", but a "good ways of doing it are".

As for adding "no go"s, that depends if agreements can be found, and how to monitor, and deal with it.



lazarus.cfg https://wiki.freepascal.org/Multiple_Lazarus#Using_lazarus.cfg_file

[Warfley]

One of the issues I see is that there are a lot of pages in the wiki right now which, in the best cases are just useless, or plainly even wrong or outdated.

I think it would be quite useful to have a basic checklist and to just look at every single wiki article and see if it is
a. still relevant (e.g. why is https://wiki.lazarus.freepascal.org/Lazarus_0.9.26_release_plan still there)
b. unique and useful (e.g. why does https://wiki.freepascal.org/unicode_use_cases exist, this could as well be just a part of unicode support page)
c. informative and well structured (unlike the web app article shown above)
d. generally up to quality standards

And I would even like to propose a workflow how this could be done cooperatively:
Create a new gitlab repository, with one branch per wiki page. For each of these branches create a Merge Requests, whose description contains the checklist. Then any user who is willing to contribute and has a bit of time on their hand could go to the gitlab, take one of the merge requests, read the article and answer the questions from the checklist.

The reason for the merge request is simple, GitLab allows for merge requests to propose changes in the browser, so changes can be directly suggested. When an article belongs to another article (e.g. $A belongs to Compiler Directives), a the merge request can be simply merged into the other merge request with just 1-2 clicks. Lastly once the merge request has been merged, an CI/CD script could update the wiki with the changes from the gitlab, or if thats to complicated/error prone, the person merging the request in the end could just copy-paste the wiki article into the wiki.
After review and maybe changes the branch can be merged and then the wiki can either be updated through a CI/CD script that is automatically run on merge, or just manually by the merger copy and pasting the contents to the article.

I've just hacked a bit around to try this out and created this small gitlab repo: https://gitlab.com/Warfley/lazwiki
There for example you could then pick out any merge request like: https://gitlab.com/Warfley/lazwiki/-/merge_requests/235
Read it, and go through the checklist if everything is fine.

If not you could directly go to changes, and comment inline or suggest changes.

If that would be of interest, all the scripts I used to do this are in the repository.

I think that such a structured approach would maybe even lead people who otherwise wouldn't know how to participate to just take out a few minutes a day to read 1-2 wiki articles and contribute that way. I certainly would do this.

[Martin_fr]

Your gitlab links don't work.

Well, lets see what the more active wiki users have to say.

But a wiki has its own editing mechanism. Putting that behind git seems strange, to say the least.
- The Wiki has "talk" pages. Not sure if a lot of use is made of it.
- The most important part of the wiki, is the ease of write access to it. (Well yes, that partly impacts quality a bit).

Your idea sounds more like a new project. A documentation team (which does have to have members), that produces the content. Making it gitlab opens it up for contributors, just the same as the source code is open for contribution.

I think (but again lets wait for others) that on the wiki, the effort has to maybe a librarians and copywriters work: take the content, sort it, maybe improve the language (or translate).
In some cases moderation, when content is offtopic or duplication.

----
Btw old release pages document the history of the project.... Is that needed, up for debate, but imho not an immediate "no".

In the past (I think removed by now) someone had started to add each pascal keyword and build in type as a wiki page. There is a point of removing it, since documentation for those exists already.

[Warfley]

I forgot to make the gitlab public, should now be accessible.

The reason why I would put it behind gitlab is simply because it allows to manage each page individually. Otherwise you would need some mechanism to find out which wiki pages have already been updated and which are still open to check.

Also this allows to have basically discussions and a record on each page individually. Unlike just editing the wiki pages of others, you could make suggestions, explain yourself, and get your changes reviewed (and potentially rejected) by others.

This also wouldn't require so much of a wiki team, as basically anyone can contribute to merge requests in gitlab. It only takes a project member to finally click the merge button (so some oversight people need to be appointed).

[TRon]

Well, lets see what the more active wiki users have to say.

Not having being active on the wiki for a while (but used to) I can honestly say .. mew.

Btw old release pages document the history of the project.... Is that needed, up for debate, but imho not an immediate "no".

Indeed. But as a second one take a look at the user changes pages etc. It is a wealth of information in case someone ask a question about some feature that is not working only to find out TS is using a version that is too old. Without these opages it is almost impossible to have a (quick) look at that kind of information.

In the past (I think removed by now) someone had started to add each pascal keyword and build in type as a wiki page. There is a point of removing it, since documentation for those exists already.

Not removed. It has its own namespace now. From origin it was a wikibook and personally I always wondered why it was included in the wiki but since the wiki was starting to incorporate something similar for at least some keywords it was not a too strange idea to do.


imho the wiki tries to do too much. From reference manual, blog site, instructions manual, personal pages, component reference manual, to examples hub and that is ofc fine but it lacks structure. There are some active wiki editors that have been trying for the last year (or is it 2) to clean things up a little and add some logic in the structure of the pages. Some pages have very low quality as is bound to happen when those that actually know can spend their time better with actively improving compiler/rtl instead of 'wasting' it to editing a wiki. Thereby writing editorial pages is not everybody's virtue as well.

[Martin_fr]

Also this allows to have basically discussions and a record on each page individually.

Same as the talk page that comes with each page.

The wiki also has a "patrolled" mechanism. On the "recent changes" it shows a marker for anything not yet patrolled. And on the history's diff viewer changes can be marked as patrolled. (Likely needs a moderator account)

As for outdated => that needs regular checking. Some pages may outdate faster than others...

[Warfley]

Btw old release pages document the history of the project.... Is that needed, up for debate, but imho not an immediate "no".

From what I can see there are the "Release Notes" pages, which exist for pretty much all major releases, and then the "Release Plan" pages, of which only 3 or so exist, and I think that they don't serve any purpose for documentation that the release notes don't serve. The only thing you could read from them is what features were not implemented 15 years or so (whenever 0.9 was live) ago.

There may be value in discarded ideas, (e.g. with FPC there would probably be interesting to have pages on why for example inline variables are not added, because this topic comes up every few years in the forum), but I think the context of these "Release Plan" pages is not the right one.

In the past (I think removed by now) someone had started to add each pascal keyword and build in type as a wiki page. There is a point of removing it, since documentation for those exists already.

There is at least on for most compiler switches. Which are also documented in the official doc.

imho the wiki tries to do too much. From reference manual, blog site, instructions manual, personal pages, component reference manual, to examples hub and that is ofc fine but it lacks structure. There are some active wiki editors that have been trying for the last year (or is it 2) to clean things up a little and add some logic in the structure of the pages. Some pages have very low quality as is bound to happen when those that actually know can spend their time better with actively improving compiler/rtl instead of 'wasting' it to editing a wiki. Thereby writing editorial pages is not everybody's virtue as well.

Recently I've just gone to the wiki and clicked random to see what comes up, this is how I found all of these examples I've posted before. Personally I feel that there is just to much on the wiki, or at least to unstructured. Thats why I proposed a more structured approach to once go through all of the pages and look at them using a checklist or something more-or-less objective to judge these pages.

For example, I'm not in favor of deleting anything due to the potential knowledge loss, but there are alot of pages for some projects that haven't received updates in 10 years or more so I would suggest that these should be marked.
Other things are, for example I really like that there are pages for third party libraries and tools on the wiki, but also when I develop my application I usually preferr things included with FPC and Lazarus (less dependency management, all under the same licensing, known update and bug reporting mechanism, etc.), So I think it is also important to clearly mark on the wiki what is third party and what is part of Lazarus, what is Part of FPC and what is third party.

The wiki also has a "patrolled" mechanism. On the "recent changes" it shows a marker for anything not yet patrolled. And on the history's diff viewer changes can be marked as patrolled. (Likely needs a moderator account)

It's just a suggestion, because from an outside perspective, it looks like the current system isn't really working. I've seen many pages (like the web apps page) where edited recently, so someone was looking at them, yet this page remains as useless (potentially even counterproductive when new programmers think that this is the main resource for web development, and therefore not giving lazarus a try) as it is.

In my oppinion there needs to be a structured approach, where a set of criteria is defined and all the wiki pages are checked one by one if they satsify these criteria and are adopted respectively

[Martin_fr]

1) clarity of a page => copywriter needed.
I don't think the git approach will solve that, unless it simply prevents pages from being added. Many contributors aren't native English speakers, and so if the merge requested, the request would sit there until a native speaker wanted to deal with it.

2) structure
Similar. It is additional work to add categories, links, portals, group into namespaces, split or join pages.

3) patrolled
As there are few to patrol, this probably only indicates: no vandalism or spam.


Overall, all of those points need manpower first.

They could then benefit from tools helping to organize some of the processes. But those tools should be in the background. They shouldn't affect the people who want to add to the wiki (otherwise we loose those people, and then we don't have better content, we just have less).

I don't know how to easily have a list of
- need copywriter pages
- need indexing pages
- "last outdated" review by date.

There are some tags that can be added (no idea how, just stumbled upon).
The media wiki docs are public avail, so its possible to find out what is available for use.


For outdate translation, they could be marked with a template that puts a div with absolute position in one of the screen corners.
Not sure if a but could find candidates for such pages.


For people who add content regularly: Guidelines and documentations of templates to use, and how to use namespaces and categories.

 

[TRon]

Recently I've just gone to the wiki and clicked random to see what comes up, this is how I found all of these examples I've posted before. Personally I feel that there is just to much on the wiki, or at least to unstructured. Thats why I proposed a more structured approach to once go through all of the pages and look at them using a checklist or something more-or-less objective to judge these pages.

imho there are some things that should have been split up and/or categorized (a lot earlier). There is a lot going on...

For instance Lazarus (and with that I mean the IDE, usage, extending, configuring, debugging etc) lacks a real manual even though there are actual manuals that exist. All things related to that deserves its own space.

A similar thing is available for the FPC compiler.

Then for both we have the "developer notes", e.g. user changes, new (language) features, howto build, install etc. which is more technical, perhaps extended with things like how to add support for a new platform or how some of the compiler internals work, same for Lazarus e.g. how to add a new widgetset, howto extend the IDE etc.

Then we have the Pascal language itself, thus actually a Pascal reference manual similar to the official Free Pascal manual. I do understand the need why a user-edition of this exist. imho it should have been a separate wiki from the start.

Then there are the component reference pages, which is similar to the official LCL docs but sometimes extended with some additional notes and/or examples.

Then we have pages for 3th party components/packages. And yes some of them imho do deserve their own space just by the sheer complexity or huge amount of available features (think of something like BGRA bitmap)

While I personally would envision/favour something like a component database that has information for all components (could be filtered as per your suggestion to keep it LCL only) so that it is possible to lookup a certain component/property quickly to be able to read their explanations (when available) and be able to view some examples (again if available).

Separating these things would imho improve things considerably as when you leave that all out there is not much left except perhaps for what now is categorized in platform portals.

And that is where things get a bit more complicated because even though a topic like retrieving internet-pages using httpclient deserves its own topic, it is also very platform specific when it comes to how to let it work for a particular platform. And this is just one of the many examples that makes it hard to categorize. Do we do it either in a topic sub-categorized by/per platform or would it be more logical to do it the other way around e.g. by platform and then sub-categorized by/per topic ? imho a wiki is not a good medium for these kind of things (at least I do not know of an add-on which would be able to make such things easier).

But even while it would be practically possible to realize something that is suitable for all situations and as already stated... manpower ....

[af0815]

In the past 10 yrs I have found discussion about the wiki and some tools like better visualization of the language parts and diffences, but this discussion are only time wasting. The existing tools for the wiki were never accepted.
And a solution over a third-party tool like git or similar is not a good way, the wiki community have some working ways, but they must be accepted.

My 2 cents

It is not a problem of manpower, it's more a acceptance problem.

[Thaddy]

Well,
Ask for peer review before you edit...
I usually do that. (as with scientific entries on wikipedia itself)
Problem with our wiki is that people do stupid edits that subsequently need to be reversed. That is a pain in the back-side and often not necessary.

The quality of the current wiki is beyond editting: very low.

It would be better if peer review is required and that can be enforced.

[Martin_fr]

If some volunteers could just pick a wiki page thats up for review and then look at it with a given style guide, I think many could put a few minutes a day into this, and with just a few volunteers in a structured way the wiki could be cleaned up and maintained quite efficiently.

Well, the problem is to get the volunteers, rather than the process itself....

But you could always start yourself on some articles of your choice.
That would at least be some articles, rather than none.

If others want to join in, you can then see what there ideas are how to process/coordinate, and find a between them and you.
(And maybe get the existing wiki moderators involved)

The checklist is a start, but may depend on interpretation.
https://gitlab.com/Warfley/lazwiki/-/merge_requests/235

First and most important point.
- Can (and how can) the work that the author(s) put into the page be preserved.

Any removal must have tremendously good reasons, and those reasons should be established by a group (once established they can be applied by a single person, if/when there is on doubt that they fit a specific article)

Does the title match the content

Is partly subjective.

Is the article written neutrally

Again, I have written articles on debugging, where I recommend FpDebug. Recommendation is not neutral.

Is the Article up to date

+1
But what if not?
Half the IDE help pages are outdated. But better than none. So removing is not an option.

Is the Article well written (no obvious spelling or gramatical errors)

+1
Though there is a difference between "well written" and "written without spelling or grammatical mistakes" (btw, accident or pun, that your checklist has a spelling mistake in "grammatical"? )

"well written" to me means: Concise, yet comprehensive. Using a language style befitting the subject. And - given the international audience - avoiding too advanced English.

Is the Article unique or overlaps with existing articles

+1
Though several articles on a subject may exist, if they refer to each other. And briefly explain why both exist.
And if the don't, the solution may be to add this.

E.g.: https://wiki.freepascal.org/SVN_to_GIT_Cheatsheet#Alternative_to_this_Page

Does this need to be it's own Article or would it better be incorporated into another one

Kind of duplicates the above point

Is the Article adding value

Highly subjective

Are all links still reachable

+1

Is there an english version of the article

What if not?

Are all other languages up to date with the english version

+1
Needs some form of easy to add marker (some template)

For third party packages and tools: Is it clearly marked as such

ok

For packages and third party tools: Is the License noted
 For third party packages and tools: Is an Author named/linked
 For third party packages and tools: Is there a link for further information
 For third party packages and tools: Is it still actively maintained

if not, the info may still be of interest

Are all categories sensible

ok, but subjective

Is it tagged with the language category

Do we have a documentation of all the templates (auto category, language bar ....) that are added, and what they exactly do, ....?

[Martin_fr]

Btw, "subjective" doesn't mean it can't be a criteria, at least at some point, eventually.

But, before that it should be refined, and reviewed by a group of different people. Using a good amount of samples from the wiki to write detailed guidelines....
Not sure, if worth the effort...

And if not, then only used with greatest care, and still instead of having pre-approved guidelines, get a peer review on the opinion for each article, when and if you deem an article to fall into such a category.

[trev]

The short answer is that the state of the Wiki boils down to there being insufficient people writing new content and, more importantly, maintaining the existing content.

Foreign language pages are generally (exceptions are probably the German and Russian pages) in an even worse state than the English pages because there are even fewer people contributing to them.

I spent just over two years writing, re-organising and updating Wiki content on a daily basis, although due to other commitments I've not been very active for the last year.

Apart from redesigning the Wiki home page with the agreement of the FPC and Lazarus teams to feature Topic Portals, the vast majority of my work was in writing new macOS Portal https://wiki.lazarus.freepascal.org/Portal:Mac content, with diversions to reorganise and update the https://wiki.lazarus.freepascal.org/Projects_using_Free_Pascal pages, translate the German pages on ARM  https://wiki.lazarus.freepascal.org/ARM_Embedded_Tutorials and AVR https://wiki.lazarus.freepascal.org/AVR_Embedded_Tutorials microcontrollers, create the FreeBSD Portal https://wiki.lazarus.freepascal.org/Portal:FreeBSD, create the New Users Portal  https://wiki.lazarus.freepascal.org/Portal:New_Users, create the HowTo Demos  Portal https://wiki.lazarus.freepascal.org/Portal:HowTo_Demos, update and reorganise https://wiki.lazarus.freepascal.org/Installing_the_Free_Pascal_Compiler**, update and reorganise https://wiki.lazarus.freepascal.org/Installing_Lazarus**, update and categorise the Lazarus IDE pages https://wiki.freepascal.org/Main_menu, and categorise the uncategorised Wiki pages.

**I had help from David Bannon who did most of the the Linux installation content and WP for the Windows installation content.

I disagree that the content should be created in git or other rcs before being added to the Wiki - placing such barriers to contributions would only stop users from contributing which is not something we can afford. The same goes for any suggestion to enforce "guidelines" for contributions.

As to possible missing "make" content for Windows, if it is still viable you can retrieve it from the history pages - yes, the history pages are very necessary and I disagree that any should ever be deleted. They do no harm, but come in handy when you least expect it.

As my background was in writing legal reference works for a multi-domestic law publisher before pivoting to programming, I trust that the original content I have written for the Wiki is understandable and useful despite my not having followed the any guidelines other than common sense

Last, but not least, remember that a Wiki is "a website or online resource that can be edited by multiple users".

The harvest is plentiful, but the workers are few.