general discussion about Wiki rules, style guidelines etc.

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

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

Post by Roy_043 »

david69 wrote: Thu Jun 16, 2022 9:32 am to aswer you, why not, [[ParDesign_Pad|PartDesign Extrude]] if it is more speakfull.
IMO you are not thinking this through. Planting the word "Extrude" in the brain of a new user, when the whole FreeCAD community uses "Pad" for the same command is not a good idea. "Write whatever you want" is not a good basis for consistency.
david69
Veteran
Posts: 1760
Joined: Wed Jan 01, 2014 7:48 pm

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

Post by david69 »

in that case, you change back. It is what was I explained.

last week, on demand, I had to change the translation of the command Thickness (one of the "hidden command) under Part Design on the GUI. it was inappropriate after couple yrs. Changing GUI means I needed to change the wiki, everywhere the previous word was. it is rare, up to now.
User avatar
uwestoehr
Veteran
Posts: 4961
Joined: Sun Jan 27, 2019 3:21 am
Location: Germany
Contact:

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

Post by uwestoehr »

Roy_043 wrote: Wed Jun 15, 2022 8:25 pm How would you deal with Std_Import, Part_Import and Mesh_Import f.e.? They would all have a claim to the same page name. Your suggestion would also break the translation mechanism.
As I wrote in these cases it is of course sensible and important to keep the prefix.

However these are exceptions, for the vast majority of commands, their name is unique and the prefix can be omitted.
User avatar
uwestoehr
Veteran
Posts: 4961
Joined: Sun Jan 27, 2019 3:21 am
Location: Germany
Contact:

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

Post by uwestoehr »

Roy_043 wrote: Wed Jun 15, 2022 9:19 pm How would you write a beginner's tutorial that uses the Draft_Rectangle, the Part_Extrude and the Std_ViewFitAll commands without using prefixes?
Yes, without the prefixes. We speak here about what the user reads. He reads e.g "rectangle tool" and can click on it when he want to. He gets the right Wiki page and that's it. Why do we have to bother especially beginners with internal names?
Roy_043 wrote: Wed Jun 15, 2022 9:19 pm How would you write a paragraph that compares Part_Extrude and PartDesign_Pad? Would you use "Extrude" and "PartDesign Pad" if the page belongs to the Part WB? And "Pad" and "Part Extrude" for a page in the PartDesign WB? Would that not lead to confusion?
Write e.g. "the [[Part_Extrude|extrude]] tool from the Part workbench".

This is user-friendly in my opinion.

Again, there might be cases where the prefix would help, but there is no reason to force a rule just because there are such cases.
Roy_043 wrote: Wed Jun 15, 2022 9:19 pm Which texts would be allowed in the Docnav? Should they always be the same as the menu text, or can a writer create an alternate version of the actual command name or make something up ("Part Slice Apart"/"Slice Apart"/"Slice a Part"/"Split Shapes"/"Slice and Explode")?
One can use a short name describing the command. So choose e.g. "Slice Apart" for the command Part_SliceApart. Just assure that this term is then consistently used in the docnav of the workbench.
User avatar
uwestoehr
Veteran
Posts: 4961
Joined: Sun Jan 27, 2019 3:21 am
Location: Germany
Contact:

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

Post by uwestoehr »

Roy_043 wrote: Wed Jun 15, 2022 8:58 am @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
This was just one case. See my initial post about my different points.

Concerning this case, why do you just revert this? Based on what rule? I got direct feedback on that page that the existing description ready very technical and unnecessarily complicated. I changed it accordingly and then it is just reversed.
my problem with this:
* One can speak about many things but just a reversion of a formatting change is not the way joint Wiki work should be.
* this was feedback from our community. It must be allowed to change a page accordingly. Personally I also understand the criticism - there is a 1. but no 2. and there are not 3 different ways. It is just like for every other program (LibreOffice, Gimp or whatever), where you can access a command via toolbar, menu and/or a shortcut.
User avatar
Roy_043
Veteran
Posts: 8411
Joined: Thu Dec 27, 2018 12:28 pm

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

Post by Roy_043 »

Regarding your remark concerning etiquette: when, if ever, do you discuss your proposed edits with previous editors? The page in question is a case in point: I updated the Usage paragraph in February 2021 to match the standard as defined by the GuiCommand_model page (FYI: model=standard=rule), and I don't remember you contacting me prior to your recent modifications. But furthermore, as I have already said on my Talk page, the shoe is really on the other foot here, you should have discussed your proposal first. This is not the way to change how to wiki is organized.
User avatar
kaktus
Veteran
Posts: 1149
Joined: Sun Aug 11, 2019 11:59 am
Location: opolskie
Contact:

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

Post by kaktus »

david69 wrote: Thu Jun 16, 2022 9:32 am
Roy_043 wrote: Wed Jun 15, 2022 8:41 pm
david69 wrote: Wed Jun 15, 2022 11:55 am why not to add an extra field giving the command, like
Your 'I write what I want' suggestion is problematic. It would mean that an editor could choose whatever he/she personally is more comfortable with. Would you want the "PartDesign_Pad" command to be identified as "Extrude" f.e.?
to aswer you, why not, [[ParDesign_Pad|PartDesign Extrude]] if it is more speakfull. to Uwe, the importance to have [[something|something else]] because it turns in an other language [[something|なにかべつ]].

yes I see your point. here my experience:

As a translator, today this is what I am doing more or less. It must be not to bad because except two or three times, some guys demand to change, it works. I suspect the Frenchies are not too vindictive. When it happens, we debate. The good point, I am alone, the bad point, I am alone.

what I mean, the guy who is writing the page and in particular the command name is supposely to be conscious that he is not there to please himself. Why would he put something extravagante and if it is the case, then we change keeping in mind there is Crowdin behind.

Myself, how many times I back an forth on some command name because too long, not enough speaking, do not translate what the coder is implementing and in parallel checking Crowdin (and it is here I've found "hidden" commands).

the drawback of that: I need to double check on each pages using this command [[Std_original_command/fr|Std Ma traduction]] that it is the wording given on the original page, and that can be painfull.

@kaktus & @FBXL5, as you are pretty active on wiki, how do you work? and @pmlee ? it seems you are starting to translate, do you have an opinion?
adrianinsaval wrote: Wed Jun 15, 2022 9:42 pm Sounds like there are reasons for the status quo, who would have thought ;)
so the prefixes are actually useful in many places and having them in some places and not in others is inconsistent and can be confusing.
yes, they are important.

I wanted to avoid commenting on this discussion, but I see that this is not possible because I have been called to the blackboard.
:roll:

Yes, the issues raised here are not easy to resolve.
The two realities of developers and users are at odds here.

It is important to remember that programmers create for the user community so that users can use the fruits of the programmers' labor.

At present, it is problematic to have similar function naming in many workbenches. So it is not possible to omit prefixes that identify the parent of a function. Because chaos will ensue and no one will know which function the description refers to. :o

As a translator of Wiki documentation, I omit these prefixes whenever possible so that the resulting description is not cluttered and tangled with constantly repeating names. This sometimes looks bad in translation. :idea:


But please note that I wrote "whenever possible."
The use of such simplifications must be done carefully to make the translation of the documentation valuable.
So that the reader is not unintentionally misled. And in this case it is not difficult. :?

I think that these prefixes cannot be omitted (eliminated). And finding a good solution (compromise) may not be possible (nobody will rebuild the whole program code to change a few function names to not repeat them).

I have pointed out before that translators have a difficult job, because they have to convey the intentions of a text to make it valuable. Often a literal translation is nonsense and undesirable.
However, at this point I would like to remind you that every translator is not tied and is free to prepare his own translation. :idea:

*************************************************

Maybe my comment doesn't bring much new to the topic. However, I highlighted the main points of the problem.

Is it possible to use syntax in the source documentation (EN) as in the case of translators e.g:

Code: Select all

[[OpenSCAD_Workbench/pl|Środowisko pracy OpenSCAD]]
With this mechanism, this problem can be less annoying to the user-readers.
maybe the notation won't be so cumbersome ...

Code: Select all

[[Draft_Rectangle|Rectangle]]
Of course, then the tutorial / description text must be properly worded. :idea:
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
FBXL5
Posts: 957
Joined: Sat Aug 03, 2019 8:45 pm

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

Post by FBXL5 »

david69 wrote: Thu Jun 16, 2022 9:32 am @kaktus & @FBXL5, as you are pretty active on wiki, how do you work? and @pmlee ? it seems you are starting to translate, do you have an opinion?
As a user I would look for the words I read in the GUI.

With my underdeveloped communication skills I prefer to edit the wiki in a way that causes as little friction as possible. The easiest way to do so, is to follow a standard and trying to be consistent according to recently updated.

In fact I have a talent to choose the wrong examples and the get told off by Roy, but I think I have improved over the last months. 8-)

For consistency reasons I would follow Roy's/the GUICommand_model's way where it is applicable. An advantage is that if the inscription of the button and the menu item should change, the skeleton of the page can stay unaltered and no docnav needed to be adapted. And that is why I handle translation pages in this manner, as well.
chrisb
Veteran
Posts: 53786
Joined: Tue Mar 17, 2015 9:14 am

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

Post by chrisb »

Concerning the use case mentioned above where things had been reverted:

The general rule must be:
- It is possible to change things on a wiki page without asking former editors
- Reverting edits must be discussed before executing them.

These rules are based on the idea that editors give their best.

There are of course exceptions - or better: extensions - to this rule:
- If there is an obvious page maintainer, things should be discussed with him
- a difficult one: changing something that had been changed very recently, should be discussed with the last author. This is problematic, because usually editors just want to improve the current state and don't look at the history.
- if an edit is completely out of whack, it could be sensible to shoot first and discuss later.
...
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
User avatar
onekk
Veteran
Posts: 6098
Joined: Sat Jan 17, 2015 7:48 am
Contact:

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

Post by onekk »

Hello.

There have been recently some discussion about ambiguity of terms.

https://forum.freecadweb.org/viewtopic. ... 88#p602188

Mostly related to the Part that could generating confusion among new users.

Regarding the Scripting section, I think that is very handy to have this section when dealing with some arguments, as being most of my "forum time" on the "python scripting and macro" forum, there are many user that came there (in "scripting forum") and ask for help, it is very handy to point them at the "general page" and tell see at bottom of the page in the "Scripting section".

I hope this will not be changed in future, or maybe if "Scripting Part" will make the page too crowdy a Scripting section with a link to separate page hopefully with a meaningful title could be a "decent solution".

More in general, what is lacking is some "introductory guide, that explain clearly some thing", sorry if examples are not very clear, but:

https://forum.freecadweb.org/viewtopic. ... 55#p484455

https://forum.freecadweb.org/viewtopic. ... 89#p500989


These two post seems to be obvious but for beginners they are hard to cacth, as many messages on the forum seems to reveal.

I.e the distinction between Curves. TopoShapes, DocumentObjects and relation between them and how to go from one to another.

I know that is more a Scripting problem, but as some behaviour could be found even in the Gui when an user try to apply some actions to wrong objects, maybe making these distinctions more visible, actually they are "hidden in plain view", as ancillary phrases in the Topology and Geometry explanations.

Sorry if something is not clear or maybe OT.

Best Regards

Carlo D.
GitHub page: https://github.com/onekk/freecad-doc.
- In deep articles on FreeCAD.
- Learning how to model with scripting.
- Various other stuffs.

Blog: https://okkmkblog.wordpress.com/
Post Reply