general discussion about Wiki rules, style guidelines etc.

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
uwestoehr
Veteran
Posts: 4248
Joined: Sun Jan 27, 2019 3:21 am
Location: Germany

general discussion about Wiki rules, style guidelines etc.

Post by uwestoehr »

Dear Wiki editors,

since I handle the releases I actively contacted people to get more feedback outside of my bubble. My aim is to listen what average and new users think. Besides this, I could introduce FC to some colleagues and see how they learn. In general the Wiki is used much, I also see that what is not well documented is not used (no matter if I e.g. showed them) - no surprise :) .

As a developer I force myself to improve the Wiki based in the feedback I got, when I think something is missing or too technical, etc. However I sometimes see that my changes are just reverted and that some Wiki maintainers are unhappy with it. In some private discussions with them, I hear that there are rules and the aim of this discussion is to unveil them.

The goal of this thread is therefore to discuss the existing Wiki pages where our Wiki principles are documented:
* https://wiki.freecadweb.org/GuiCommand_model
* https://wiki.freecadweb.org/WikiPages
I hope to get this way less frustration since then the info is available for everybody and by a discussion some things can be changed by the community.

Here are my 2 main points:

-----------------------------------
1. Let's focus on the readability and hide the technical terms to the sections where they belong to (scripting etc.)

Something I often heard is that the Wiki tries to be very correct with technical terms. For example in links we repeat the technical name. For example in the "See Also" fields of commands we repeat the prefix of the workbench. This was criticized since this is done in many links and gives the Wiki often a touch that one needs expert knowledge to learn commands. However unless you script with Python, users are not interested in knowing internal names. Just yesterday I had feedback that the prefix can even be confusing for average users. Note hereby that the techical feature names are given by developers and when they are "invented" one doe snot think about later documentation, how it would look in the Wiki, in YouTube videos or blog posts.

Let me give me two examples:
* First few days back we added pages for the Web workbench. On the main page:
https://wiki.freecadweb.org/Web_Workbench
we link the pages with user-friendly texts like "Set URL". People this way knows that the links page is obviously about setting an URL. If they need this, they can click the link. However in the different pages the situation is more technical. Take e.g. this page:
https://wiki.freecadweb.org/Web_OpenWebsite
In the Docnav the user reads "BrowserSetURL". This is technically of course correct, but why can't we just use "Set URL"? In the See Also field the users reads "Web BrowserSetURL", so even more technical. I think the user knows he reads about the web workbench, so also here the term "" would do the job in my opinion. (In cases where the workbench matters, it is of course sensible to have it as prefix to avoid confusion.)

* a user tried
https://wiki.freecadweb.org/Part_SectionCut
and asked why is it about Part. He cut assemblies and the parts in there were made using PartDesign. I explained him that the feature is technically implemented in the part workbench and he replied "why is this info important for any user? It works for different parts and assemblies, so just omit "Part".

-----------------------------------
2. Let's allow what MediakWiki allows us (math, figures etc.)

I like that we use MediaWiki, the same engine like the Wikipedia. Therefore new users might already know its syntax. Moreover the Wikipedia leads to continuous improvements in the MediaWiki software due to their massive user feedback. We should make more use of the features the engine provides us. For example there is a beautiful formula renderer and the formula syntax is the one of LaTeX. Therefore formulas can easily be created using one of the online LaTeX generators.

An Example: I once made a start in
https://wiki.freecadweb.org/B-Splines#Math
and I would like to transform more formulas and add new ones. It looks professional an I think sometimes a proper equation explains more than a long text.

-----------------------------------
I am curious to hear your opinion. many thanks in advance and regards
Uwe

@Roy_043 , @david69 , @mario52 , @renatorivo
User avatar
Roy_043
Veteran
Posts: 5231
Joined: Thu Dec 27, 2018 12:28 pm

Re: general discussion about Wiki rules, style guidelines etc.

Post by Roy_043 »

uwestoehr wrote: Tue Jun 14, 2022 6:56 pm In some private discussions with them, I hear that there are rules and the aim of this discussion is to unveil them.
This surprises me. The GuiCommand_model page is no secret and has been pointed out to you in the past. Why start the discussion in this manner?
User avatar
kaktus
Posts: 719
Joined: Sun Aug 11, 2019 11:59 am
Location: opolskie
Contact:

Re: general discussion about Wiki rules, style guidelines etc.

Post by kaktus »

uwestoehr wrote: Tue Jun 14, 2022 6:56 pm
...

The goal of this thread is therefore to generate a Wiki page where our Wiki principles are documented. I hope to get this way less frustration since then the info is available for everybody and by a discussion some things can be changed by the community.

...

do you mean this site :?:

https://wiki.freecadweb.org/WikiPages

;)
wierny padawan mistrza arturromarr
Twórca polskiej wersji Wiki dla FreeCAD, współwórca polskiej wersji GUI.
"Cierpliwym być musisz, by wiedzę zgłębiać tajemną, gdyż ciemna strona mocy niszczącą i silną jest".
User avatar
uwestoehr
Veteran
Posts: 4248
Joined: Sun Jan 27, 2019 3:21 am
Location: Germany

Re: general discussion about Wiki rules, style guidelines etc.

Post by uwestoehr »

Thank you both, I updated my initial post accordingly.

So the aim is to discuss the existing rules then. For example in
https://wiki.freecadweb.org/GuiCommand_model
Its discussion page is empty and searching the forum I cannot find a thread where the rules given there were discussed or where they come from.

I made my points and would like to change the rules accordingly for the reasons I gave.
User avatar
Roy_043
Veteran
Posts: 5231
Joined: Thu Dec 27, 2018 12:28 pm

Re: general discussion about Wiki rules, style guidelines etc.

Post by Roy_043 »

On the one hand you want simplicity, on the other complexity. This alone makes it hard, for me at least, to understand you.

Regarding the 1st issue:
I want to see if I can find a previous discussion first.
Edit: Found it: https://forum.freecadweb.org/viewtopic. ... 30#p486212

Regarding the 2nd issue:
The page you mention can only be edited by you. No other editor, and probably very few FreeCAD users, understand the mathematics and (Wiki) formulas involved. This is problematic IMO. We need to keep the Wiki code very basic so that the average editor, without a university degree in mathematics, can understand and update pages. Another concern is that the formulas probably won't survive the transition to GitHub. Why not put the page on some Math wiki/blog instead?
User avatar
Roy_043
Veteran
Posts: 5231
Joined: Thu Dec 27, 2018 12:28 pm

Re: general discussion about Wiki rules, style guidelines etc.

Post by Roy_043 »

uwestoehr wrote: Tue Jun 14, 2022 6:56 pm * a user tried
https://wiki.freecadweb.org/Part_SectionCut
and asked why is it about Part.
I did request a name change for this command (Std_SectionCut). :mrgreen:

If the command names are indeed so confusing isn't that where we should look first? In other words: choose better names?
chrisb
Veteran
Posts: 43406
Joined: Tue Mar 17, 2015 9:14 am

Re: general discussion about Wiki rules, style guidelines etc.

Post by chrisb »

I would separate the LaTeX formula style from the rest of this discussion, as it seems indeed so as if you want simplifactions and more complex stuff at the same time, just as it pleases in individual cases.

Concerning formulae:
An in-depth B-spline page needs quite some mathematical background and the LaTeX engine is indeed famous for its layout of formulae.

Concerning the naming of wiki pages:
I currently like the systematic way of naming these pages. The example with the section cut is an unlucky one, because I am with Roy, that it has just the wrong name. If it is named the way it is, it should be moved to Part workbench, if it stays where it is, it should be called "Std_SectionCut".
The systematic approach, once understood, makes it easy to find things if you know in which workbench to look, and it is a good aid for the helpers here if they reference something in the wiki using the wiki tag.

I see that things are different if you are just searching for something where you don't know in which workbench it is; and some functions are to be found in unexpected places, e.g. I would expect the Clone rather in Part WB than in Draft. But the search function in the wiki is not too bad and searching for "Clone" yields the expected results in Arch and Draft.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
User avatar
Roy_043
Veteran
Posts: 5231
Joined: Thu Dec 27, 2018 12:28 pm

Re: general discussion about Wiki rules, style guidelines etc.

Post by Roy_043 »

@uwestoehr You forgot to mention the issue that sparked this discussion:

Your Usage paragraph:
https://wiki.freecadweb.org/index.php?t ... 8806#Usage

The Usage paragraph reverted to the standard layout.
https://wiki.freecadweb.org/index.php?t ... 2828#Usage
david69
Veteran
Posts: 1083
Joined: Wed Jan 01, 2014 7:48 pm

Re: general discussion about Wiki rules, style guidelines etc.

Post by david69 »

I understand your point Uwe and I did it by the past and ouch, my fingertips...

one rule I adopt on the French wiki, I am "lucky", I am the only one but what happens tomorrow is somebody breaks "my rules"?

take:
Capture du 2022-06-15 13-25-49.png
Capture du 2022-06-15 13-25-49.png (10.8 KiB) Viewed 514 times
in French
Capture du 2022-06-15 13-27-33.png
Capture du 2022-06-15 13-27-33.png (11.88 KiB) Viewed 514 times

I remove FEM because I am in the FEM workbench. Now if there is a command which is not the command of the page, I'll put the Workbench+the_command to show to the reader in which wb he must use the command and to avoid some confusion.

chrib wrote:
I currently like the systematic way of naming these pages. The example with the section cut is an unlucky one, because I am with Roy, that it has just the wrong name. If it is named the way it is, it should be moved to Part workbench, if it stays where it is, it should be called "Std_SectionCut".
The systematic approach, once understood, makes it easy to find things if you know in which workbench to look, and it is a good aid for the helpers here if they reference something in the wiki using the wiki tag.
it is an help, definitively for the English reader, for all other languages, it is lost. time by time on the French forum I explain the structure of the GUI underlying one can read the exact name of the command and then can find back the corresponding wiki page, but i do it seldomely.

why not to add in hard way in the wiki page (2000 pages pfff) the command and leave some freedom for the rest.
in § Description

FEM ResultsPurge deletes all result objects and all result meshes from the active analysis container in the Tree view.
becomes
FEM Results Purge (command FEM_ResultsPurge) deletes all result objects and all result meshes from the active analysis container in the Tree view.

take that one Path_OpActiveToggle
why not to add an extra field giving the command, like
Capture du 2022-06-15 13-43-39.png
Capture du 2022-06-15 13-43-39.png (18.29 KiB) Viewed 514 times
the docnav will second the name of the page but becarefull: in French, I break my head sometimes to have some short and it is not all the time the case and even I need to shorten some title of pages which make the docnac not so easy to read.

only suggestions
adrianinsaval
Veteran
Posts: 3050
Joined: Thu Apr 05, 2018 5:15 pm

Re: general discussion about Wiki rules, style guidelines etc.

Post by adrianinsaval »

chrisb wrote: Tue Jun 14, 2022 10:36 pm I currently like the systematic way of naming these pages. The example with the section cut is an unlucky one, because I am with Roy, that it has just the wrong name. If it is named the way it is, it should be moved to Part workbench, if it stays where it is, it should be called "Std_SectionCut".
I understand the sentiment but a systematic naming approach is more important in the code than in the wiki, the section cut feature is implemented in Part because it depends on Part functionality, IIRC this was discussed before and you can't just rename section cut to Std while it is in Part. There are different purposes to the names here, the wiki is to educate and guide users, the command internal names are for coders. I'm in favor of having the internal name displayed somewhere but I don't think making it the displayed name is a good idea. For stuff like this IMO it's better to make a page with the internal name with a redirect to the user facing name and display that user facing name in the wiki pages. And on the subject of renaming commands, changing a command name seems more complicated than a wiki name IMO as I suspect there would be backwards compatibility issues to take into account, plus it could break scripts.
Post Reply