Forum > Documentation (Maintaining -)
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).
Navigation
[0] Message Index
[#] Next page