Forum > Documentation (Maintaining -)
Wiki Strategy
TRon:
--- Quote from: Martin_fr on July 01, 2023, 09:33:45 pm ---Well, lets see what the more active wiki users have to say.
--- End quote ---
Not having being active on the wiki for a while (but used to) I can honestly say .. mew.
--- Quote ---Btw old release pages document the history of the project.... Is that needed, up for debate, but imho not an immediate "no".
--- End quote ---
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.
--- Quote ---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.
--- End quote ---
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:
--- Quote from: Warfley on July 01, 2023, 09:45:34 pm ---Also this allows to have basically discussions and a record on each page individually.
--- End quote ---
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:
--- Quote from: Martin_fr on July 01, 2023, 09:33:45 pm ---Btw old release pages document the history of the project.... Is that needed, up for debate, but imho not an immediate "no".
--- End quote ---
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.
--- Quote from: Martin_fr on July 01, 2023, 09:33:45 pm ---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.
--- End quote ---
There is at least on for most compiler switches. Which are also documented in the official doc.
--- Quote from: TRon on July 01, 2023, 09:52:35 pm ---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.
--- End quote ---
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.
--- Quote from: Martin_fr on July 01, 2023, 09:59:31 pm ---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)
--- End quote ---
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:
--- Quote from: Warfley on July 01, 2023, 10:50:22 pm ---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.
--- End quote ---
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 ....
Navigation
[0] Message Index
[#] Next page
[*] Previous page