Please stop using: 'Invoke the command several ways'

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
Roy_043
Posts: 2390
Joined: Thu Dec 27, 2018 12:28 pm

Please stop using: 'Invoke the command several ways'

Postby Roy_043 » Mon Dec 14, 2020 8:43 pm

I keep seeing pages with this text:
Invoke the command several ways:
This sentence is not correct English. Please stop using it.

Use:
There are several ways to invoke the command:

Or:
To invoke the command do one of the following:

Don't forget to update your templates as well!
hmk
Posts: 44
Joined: Tue Sep 29, 2020 1:19 pm
Location: Berlin, Germany

Proposal: Drop 'Invoke the command several ways' and only describe button press only

Postby hmk » Thu Jan 14, 2021 4:34 pm

What I often see is that 2 usages are described:
- press the button
- select from top-level menu

Since the menu-selection is already described prominently in the {{GuiCommand}} template, I feel there is not need to repeat this again. It also hampers the reading flow a bit, I feel. Plus, both descriptions need to be kept in sync.

How do others feel about this?
User avatar
Roy_043
Posts: 2390
Joined: Thu Dec 27, 2018 12:28 pm

Re: Please stop using: 'Invoke the command several ways'

Postby Roy_043 » Thu Jan 14, 2021 5:29 pm

I would not be in favor of that. You have to consider that not all commands can be accessed via a menu and a toolbar. Some can only be accessed via a menu (Mesh_RemeshGmsh) and others can be accessed in 4 or 5 different ways (Std_ToggleVisibility). Leaving out the menu option would then be a bit strange IMO.
hmk
Posts: 44
Joined: Tue Sep 29, 2020 1:19 pm
Location: Berlin, Germany

Re: Please stop using: 'Invoke the command several ways'

Postby hmk » Thu Jan 14, 2021 5:46 pm

Roy_043 wrote:
Thu Jan 14, 2021 5:29 pm
I would not be in favor of that. You have to consider that not all commands can be accessed via a menu and a toolbar. Some can only be accessed via a menu (Mesh_RemeshGmsh) and others can be accessed in 4 or 5 different ways (Std_ToggleVisibility). Leaving out the menu option would then be a bit strange IMO.
I see, so this page should actually ADD the menu-selection: https://wiki.freecadweb.org/Draft_Annot ... itor#Usage
User avatar
Roy_043
Posts: 2390
Joined: Thu Dec 27, 2018 12:28 pm

Re: Please stop using: 'Invoke the command several ways'

Postby Roy_043 » Thu Jan 14, 2021 6:22 pm

Yes.
If you are going to implement this for the Draft WB, please note that the layout of the Draft menus has changed. The single Draft menu does not exist anymore in V0.19. Instead there are 4 Draft menus. F.e. Draft → Move should become Modification → Move. And if you add the menu option to the usage section it would make sense to also put the keyboard shortcut option on a separate line.
hmk
Posts: 44
Joined: Tue Sep 29, 2020 1:19 pm
Location: Berlin, Germany

Re: Please stop using: 'Invoke the command several ways'

Postby hmk » Fri Jan 15, 2021 8:56 am

Roy_043 wrote:
Thu Jan 14, 2021 6:22 pm
Yes.
If you are going to implement this for the Draft WB, please note that the layout of the Draft menus has changed. The single Draft menu does not exist anymore in V0.19. Instead there are 4 Draft menus. F.e. Draft → Move should become Modification → Move. And if you add the menu option to the usage section it would make sense to also put the keyboard shortcut option on a separate line.
Thanks for this valuable information. I guess I stay away from this for now. Since I just started making edits, I want to increase the impact of my changes gradually. So, especially no "mass changes" for me.
User avatar
Roy_043
Posts: 2390
Joined: Thu Dec 27, 2018 12:28 pm

Re: Please stop using: 'Invoke the command several ways'

Postby Roy_043 » Fri Jan 15, 2021 9:42 am

I completely understand that, the wiki can be a bit daunting. I still have to get an overview of many wiki related things myself.