Forum > Documentation (Maintaining -)

Wiki Strategy

<< < (4/5) > >>

af0815:
Some older discussions
https://forum.lazarus.freepascal.org/index.php/topic,57972.msg432900.html
https://forum.lazarus.freepascal.org/index.php/topic,56882.0.html

Edit:
Long Discusion in german
https://www.lazarusforum.de/viewtopic.php?f=14&t=13976

Update Wiki and install Extension Translate:
https://gitlab.com/freepascal.org/fpc/source/-/issues/27684

Warfley:

--- Quote from: Martin_fr on July 02, 2023, 09:59:55 pm ---
--- Quote --- Is the article written neutrally
--- End quote ---
Again, I have written articles on debugging, where I recommend FpDebug. Recommendation is not neutral.

--- End quote ---
Recommendations are not necessarily non-neutral. For example I often recommend against using GTK2 but I do so because it is EOL, does not receive any security updates anymore, and the usage of which may be liable under laws such as EU Regulation 2019/770. It is a recommendation, but it is based on objective criteria.


--- Quote from: Martin_fr on July 02, 2023, 09:59:55 pm ---But what if not?
Half the IDE help pages are outdated. But better than none. So removing is not an option.
--- End quote ---
At the very least, it should be marked as such. Either with a note/warning on top of the page, or a fixed div in a corner like with the platform specific articles.

Then for a later step it can be added to a list (forum post, wiki page, wiki category), so someone who has the time and knowledge can update it eventually.

Knowing what you don't know is always the first step.


--- Quote from: Martin_fr on July 02, 2023, 09:59:55 pm ---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
--- End quote ---

When I added these two points, I had this in mind: https://wiki.freepascal.org/unicode_use_cases
This page basically just states "sqlite and firebird require UTF-8 for their file paths", this information can be fully incorporated in one of the "Unicode Support" pages.

Note that there is also quite an overlap between FPC Unicode Support and LCL Unicode Support, so this can be either reduced (e.g. by not having language and FPC specifics in the LCL article), or have a common Unicode Support article and just an FPC and LCL specific article for the specific functions provided by the RTL or LCL.


--- Quote from: Martin_fr on July 02, 2023, 09:59:55 pm ---
--- Quote --- Is there an english version of the article
--- End quote ---
What if not?

--- End quote ---
One could check the article (google translate should allow getting a general overview what it tries to be) and if it seems valuable, create an english version, if it is covered by other articles, integrated into another article, and if it seems to be of little value, maybe mark it as "deprectaed" or so.


--- Quote from: Martin_fr on July 02, 2023, 09:59:55 pm ---Needs some form of easy to add marker (some template)

--- End quote ---
Maybe a category so that e.g. a german speaker who wants to help can just go to the category "outdated german" and check where it could be helped.


--- Quote from: Martin_fr on July 02, 2023, 09:59:55 pm ---
--- Quote --- For third party packages and tools: Is it clearly marked as such
--- End quote ---
ok

--- Quote --- 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
--- End quote ---
if not, the info may still be of interest

--- End quote ---
Sure, but it should be clearly visible as such. What would maybe be possible, to have a template for third party components, a table or something like that, which shows the basic information. Like Wikipedia has in: https://en.wikipedia.org/wiki/GTK

* Original author(s)
* Developer(s)
* Initial release
* Stable release
* Preview release
* Repository
* Written in
* Operating system
* Type
* License
* Website

--- Quote from: Martin_fr on July 02, 2023, 10:06:15 pm ---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....

--- End quote ---
First, the criterias I've put up there was what came to my mind and not fully thought through. That said, I had a few articles in mind that I have found with such problems to base this on. But of course this needs more work than just one guy comming up with them on the spot.

I think this can really benefit, because yeah it's a bit of effort at first, but once it is done, it will archive at least a base level of harmonization.

About the subjectiveness, this is always a spectrum, like there are things which are obviously not adding much value, e.g. https://wiki.lazarus.freepascal.org/$A is completely unessecary because https://lazarus-ccr.sourceforge.io/fpcdoc/prog/progsu1.html#x8-70001.2.1 exists, and is more thourough and as official documentation also normative (unlike the wiki which is just informative on a best effort basis).
For less obvious cases a peer review may be the best option

kupferstecher:
I remeber I said it in a discussion before: In my opinion the multiple languages are really a problem for the wiki. Searching the wiki is difficult, because the results are cluttered with the same topic for several languages. Also improving sites that have direct translations in several languages is nearly impossible.

For this issue I see 2 solutions, the
first one is to make clear that the different languages are intended to be different (like it is on wikipedia) and that they are not and shall not be one-to-one direct translations. And also to make the search language specific.

The second solution could be to completely seperate the non-english articles into a new multi-language wiki, leaving the english articles as stand alone english wiki. [That english wiki then could also be used as basis for automatic translations. The then seperated multi-language wiki wouldn't be touched by the translations]* and would still be a good basis for regional efforts or for writers prefering a non-english language.

*optional for the future

Regards~

af0815:

--- Quote from: kupferstecher on July 03, 2023, 11:44:27 am ---The second solution could be to completely seperate the non-english articles into a new multi-language wiki, leaving the english articles as stand alone english wiki. [That english wiki then could also be used as basis for automatic translations. The then seperated multi-language wiki wouldn't be touched by the translations]* and would still be a good basis for regional efforts or for writers prefering a non-english language.

--- End quote ---
-1

Martin_fr:

--- Quote from: Warfley on July 03, 2023, 11:43:27 am ---
--- Quote from: Martin_fr on July 02, 2023, 09:59:55 pm ---But what if not?
Half the IDE help pages are outdated. But better than none. So removing is not an option.
--- End quote ---
At the very least, it should be marked as such. Either with a note/warning on top of the page, or a fixed div in a corner like with the platform specific articles.

Then for a later step it can be added to a list (forum post, wiki page, wiki category), so someone who has the time and knowledge can update it eventually.

--- End quote ---

Then that should be part of the checklist.

If "marked as outdated" is a template (or one of several, as translation outdate, general outdate, IDE or FPC version outdate....) => then the templates "pages linked to" report can be used.



--- Quote ---
--- Quote from: Martin_fr on July 02, 2023, 09:59:55 pm ---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.
--- End quote ---

When I added these two points, I had this in mind: https://wiki.freepascal.org/unicode_use_cases
This page basically just states "sqlite and firebird require UTF-8 for their file paths", this information can be fully incorporated in one of the "Unicode Support" pages.

--- End quote ---
ok, but then, if the checklist is just a "reminder for you yourself", its ok. But if it is for others to help you, it is too generic.

-- Ok, last sentence, you pointed out the same, later in your reply...


In any case, my advice: Get started with the tools that are already there as part of the wiki as it is.

Maybe keep a report of it somewhere, so others can see examples of what can be done, and some will join you.

Because from my experience, this thread here (this forum discussion) will not get anyone to do anything. We had similar forum threads on various topics that all were widely agreed as "would be really good", and then the discussion ended, and nothing had been done, nor did ever get started.

Now, I don't know how to best attract volunteers. But I would guess, start doing it yourself and show off the results => not the worst way.

+ Fix spelling, grammar, phrasing and maybe style => should be fine (i.e. if you don't go to far on stylistic changes, then no one would have reason to object)
+ Add markers (template) for outdated content => no objections expected either

- On the other hand structural changes (changing title = moving page / merging or splitting) are maybe better discussed on examples.
- changing categories may also want to be peer reviewed (unless something is clearly in the wrong category, like windows API under gtk)

Navigation

[0] Message Index

[#] Next page

[*] Previous page

Go to full version