wiki housekeeping

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Post Reply
User avatar
Roy_043
Veteran
Posts: 8409
Joined: Thu Dec 27, 2018 12:28 pm

Re: wiki housekeeping

Post by Roy_043 »

heda wrote: Mon Oct 18, 2021 8:34 pm "preferred linking"
I am pretty sure that had I left these extra spaces in, one of the translators would have removed them. :mrgreen:

heda wrote: Mon Oct 18, 2021 8:34 pm it is just legacy
Yes, the Wiki has some issues in that sense...
tayozhniy
Posts: 9
Joined: Mon Oct 18, 2021 1:21 am

Re: wiki housekeeping

Post by tayozhniy »

Friends!

1) I suggest changing the design of the wiki mainpage https://wiki.freecadweb.org/Main_Page.
Rename the section "The table of contents" and state it in the following wording

Offline Documentation
This part of the wiki forms the backbone of the offline documentation shipped with the FreeCAD application. [Table of Contents|Online_Help_Toc]


Firstly, it makes no sense to emphasize here that this documentation is presented in different languages, since the entire wiki is presented in different languages, not just this part.
Secondly, I find it useful to emphasize that there are two independent parts of this wiki: The Manual and Offline Documentation.

2) I also propose to emphasize in all other parts of the FreeCAD wiki that the link is given either to the section of The Manual or to the section of Offline Documentation.
User avatar
Roy_043
Veteran
Posts: 8409
Joined: Thu Dec 27, 2018 12:28 pm

Re: wiki housekeeping

Post by Roy_043 »

tayozhniy wrote: Wed Oct 20, 2021 10:04 pmI suggest...
You are going off topic here. I also get the idea you are confused about the meaning of 'offline documentation'. The offline documentation is the documentation that a user can install on their computer. The offline documentation is assembled programmatically based on the Online_Help_Toc. In it you can find links to the Wiki, not the other way around.
tayozhniy
Posts: 9
Joined: Mon Oct 18, 2021 1:21 am

Re: wiki housekeeping

Post by tayozhniy »

Roy_043 wrote: Thu Oct 21, 2021 7:33 am...you are confused about the meaning of 'offline documentation'.
No, I am not at all confused by the term "offline documentation". But if it confuses anyone, then you can suggest another one. I don't like,
firstly, the title "table of contents",
and secondly, the list of languages, as if in the wiki only these sections are presented in all languages.
User avatar
Roy_043
Veteran
Posts: 8409
Joined: Thu Dec 27, 2018 12:28 pm

Re: wiki housekeeping

Post by Roy_043 »

IMO the selection for the offline documentation should be reduced to only the command reference pages of the default workbenches. Marking links to those pages does not seem very useful. I do not see any benefit.

The Wiki has several issues. Manageability is probably the main one. Many parts are not kept up to date. The 'Manual' is a good example. Most of it was created in 2016 and has not seen significant updates since. I feel we should focus on those issues first.
tayozhniy
Posts: 9
Joined: Mon Oct 18, 2021 1:21 am

Re: wiki housekeeping

Post by tayozhniy »

Roy_043 wrote: Thu Oct 21, 2021 7:04 pmThe Wiki has several issues. Manageability is probably the main one.
This is the issues I want to help solve.
Roy_043 wrote: Thu Oct 21, 2021 7:04 pm IMO the selection for the offline documentation should be reduced to only the command reference pages of the default workbenches. Marking links to those pages does not seem very useful. I do not see any benefit.
Offline documentation looks like a complete book with its own table of contents, with its own style. Or, if you want, not a book, but a hub. The design elements of these pages contain links to the table of contents. And that's great. Navigation in this part of the wiki is fine. This needs to be maintained.

But, getting here from any other part of the wiki, the user should be warned that he will not receive links back on these pages. And this is normal for wiki. The user will be able to simply click "back" in his browser.
Roy_043 wrote: Thu Oct 21, 2021 7:04 pmMany parts are not kept up to date... Most of it was created in 2016 and has not seen significant updates since. I feel we should focus on those issues first.
I wanted to understand that. I tried to review the entire volume, and got confused in the organization of it all. That's why I'm discussing it here.
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: wiki housekeeping

Post by heda »

tayozhniy wrote: Thu Oct 21, 2021 9:39 pm and got confused
:D fc will always be a continuous state of confusion for everyone, just at different levels.

fc is all about the organic growth, everything gets done in small pieces by different people with different opinions so by default there are always corners and states that are confusing and non-coherent, and then once in a while someone comes by trying to make a corner a bit more coherent - maybe that someone is resilient enough to make it all the way through to coherence, or maybe not - possibly leaving things in an even more confusing state than before :roll:

so it goes and tomorrow is a new day.

the point being that "fixing" the overall confusion is really hard (it is built in from the organic growth), fixing a broken link or making a confusing text less confusing is much easier, and is actually what in the end will lead to "fixing" the overall confusion (or at least make it less confusing over time).

if you want to contribute, the easiest way is just to pick something small and non-controversial and just do it and let it grow from there.
User avatar
Roy_043
Veteran
Posts: 8409
Joined: Thu Dec 27, 2018 12:28 pm

Re: wiki housekeeping

Post by Roy_043 »

tayozhniy wrote: Thu Oct 21, 2021 9:39 pm he will not receive links back on these pages
Actually these pages all should link back to the "Index" page in their Docnav (the horizontal band at the top and bottom of the page). As part of an attempt to reorganize the Index (reverted by another editor :mrgreen: ) I removed the Docnav from some pages. I'll restore those.
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: wiki housekeeping

Post by heda »

poked around a bit on wiki-linking, just to get a feeling for how it looks.

if one takes the "wanted pages", i.e. red-links that amounts to some odd 15k-ish pages and summing up the total instances on the wiki that was some 170k-ish (makes one think that it is virtually impossible to not see a red-link during a wiki session).
The high number of instances is mainly related to languages that are low in maintenance.

a guesstimate is that around one third of the red-link pages is in the typo category, or it could be wiki rot with renaming, deleting etc.
this is not counting wanted files/templates (although they on occasion seems to be listed also in the pages category), or orphan pages (which generally is a linking thing as well - orphan pages is btw a bit below 2k in the listing, but since all "xyz/en" pages pop up in the listing maybe there are a couple of hundred of them).

given that each link tends to be a bit of detective work to fix,
making a noticeable dent in the linking soup is man years of work.
it is not hard, but requires that one figures out what is "right for now" for each case

anyone mind if an open call is made for people to pitch in at the same time some basic instructions are made of how one can figure out "what is right" (yes I am aware of that most think that no one will pitch in, but if one does not try it is certain that no one will...).

for example, a simple thing to check is that any "wanted page" in non-english is bluntly wrong acc. to the fc-wiki layout, all links are supposed to be in english.

btw - my favourite red-link so far is: "Roboter Tutorium (v0.17) Simuliere die Bewegung eines Industrieroboters: richte eine Trajektorie ein, richte die Ausgangsposition ein, ändere die Roboterposition, füge verschiedene Wegpunkte ein und simuliere die Roboterbewegung."

yepp, that is a red-link in the listing of wanted pages (around 13.2k if anyone wants to look it up).
User avatar
Roy_043
Veteran
Posts: 8409
Joined: Thu Dec 27, 2018 12:28 pm

Re: wiki housekeeping

Post by Roy_043 »

heda wrote: Sun Oct 31, 2021 7:17 pm for example, a simple thing to check is that any "wanted page" in non-english is bluntly wrong acc. to the fc-wiki layout, all links are supposed to be in english.
I don't think that is correct.

Many of the wanted pages are indeed missing translations. And one source of those links, that may account for quite a few, are the 'navis'. See image.

24 languages, ca. 18 unmaintained.
Ca. 20 workbenches.
Let's say 20 tools per workbench.
18 * 20 * 20 = 7200 wanted pages.

These navis are an issue in terms of maintenance. Whenever a page is added to a WB 24 navi templates need to be updated. To reduce the red links caused by a navi you would have to accept a mix of links to translated pages and English pages within the same navi.
Attachments
mesh-navi-german.png
mesh-navi-german.png (24.5 KiB) Viewed 3634 times
Post Reply