[TechDraw] updating Wiki pages

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

[TechDraw] updating Wiki pages

Postby uwestoehr » Sat Nov 02, 2019 1:46 pm

As I am learning TechDraw I noticed that the Wiki pages for TechDraw are outdated (also in respect to FC 0.18). For example there is no menu TechDraw → New Pick.

Therefore I volunteer to update the Wiki pages but I don't know if and how pages should be renamed. I mean, from the user's perspective the Wiki should use the menu names, not internal programming code names. So
https://www.freecadweb.org/wiki/TechDraw_New_Pick
should maybe become
https://www.freecadweb.org/wiki/TechDra ... g_Template

I am asking because I don't know the policy. Maybe the Wiki page names should stay stable and one only use the current menu names?
wandererfan wrote:
Tue Nov 07, 2017 6:30 pm
.
User avatar
wandererfan
Posts: 4078
Joined: Tue Nov 06, 2012 5:42 pm

Re: [TechDraw] updating Wiki pages

Postby wandererfan » Sat Nov 02, 2019 1:59 pm

uwestoehr wrote:
Sat Nov 02, 2019 1:46 pm
Therefore I volunteer to update the Wiki pages but I don't know if and how pages should be renamed. I mean, from the user's perspective the Wiki should use the menu names, not internal programming code names.
Go ahead and change the names. Those pages were my introduction to wiki (among other things), so there are lots of naming issues (icon names, image names, page names, ...). We can always make the original page redirect to the properly named page.
I am asking because I don't know the policy. Maybe the Wiki page names should stay stable and one only use the current menu names?
The only policy about wiki naming I know is that the "What's this" in the Gui is supposed to match the page name.

Wiki regulars might have some insight.
renatorivo wrote: ping
vocx wrote: ping
Kunda1 wrote: ping
User avatar
uwestoehr
Posts: 1792
Joined: Sun Jan 27, 2019 3:21 am

Re: [TechDraw] updating Wiki pages

Postby uwestoehr » Sat Nov 02, 2019 2:09 pm

wandererfan wrote:
Sat Nov 02, 2019 1:59 pm
Go ahead and change the names. Those pages were my introduction to wiki (among other things), so there are lots of naming issues (icon names, image names, page names, ...). We can always make the original page redirect to the properly named page.
OK. I am already at it now. I also sent a PR to uniform naming and tooltips in a dialog. More will follow bit by bit when I revise another feature and its corresponding Wiki page.
renatorivo
Posts: 2611
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: [TechDraw] updating Wiki pages

Postby renatorivo » Sat Nov 02, 2019 5:32 pm

Code: Select all

/===========================================================================
// TechDraw_NewPage (with template choice)
//===========================================================================

DEF_STD_CMD_A(CmdTechDrawNewPage)

CmdTechDrawNewPage::CmdTechDrawNewPage()
  : Command("TechDraw_NewPage")
{
    sAppModule      = "TechDraw";
    sGroup          = QT_TR_NOOP("TechDraw");
    sMenuText       = QT_TR_NOOP("Insert new Page using Template");
    sToolTipText    = QT_TR_NOOP("Insert new Page using Template");
    sWhatsThis      = "TechDraw_New_Pick";
    sStatusTip      = sToolTipText;
    sPixmap         = "actions/techdraw-new-pick";
}
https://github.com/FreeCAD/FreeCAD/blob ... ommand.cpp
vocx
Posts: 5206
Joined: Thu Oct 18, 2018 9:18 pm

Re: [TechDraw] updating Wiki pages

Postby vocx » Sat Nov 02, 2019 6:06 pm

uwestoehr wrote:
Sat Nov 02, 2019 1:46 pm
...
Therefore I volunteer to update the Wiki pages but I don't know if and how pages should be renamed. I mean, from the user's perspective the Wiki should use the menu names, not internal programming code names.
...
The wiki pages should be named as the code shows in the sWhatsThis field.

https://github.com/FreeCAD/FreeCAD/blob ... d.cpp#L160

Code: Select all

CmdTechDrawNewPage::CmdTechDrawNewPage()
  : Command("TechDraw_NewPage")
{
    sAppModule      = "TechDraw";
    sGroup          = QT_TR_NOOP("TechDraw");
    sMenuText       = QT_TR_NOOP("Insert new Page using Template");
    sToolTipText    = QT_TR_NOOP("Insert new Page using Template");
    sWhatsThis      = "TechDraw_New_Pick";
    sStatusTip      = sToolTipText;
    sPixmap         = "actions/techdraw-new-pick";
}
Why? Because the Std_WhatsThis tool uses this name to display the proper help page.

That is, click on the Std_WhatsThis button, then click on a TechDraw Workbench button. If the offline help files are installed, the documentation should open exactly in that page. The offline help files are generated from the wiki pages, so the names must match.

So, in my opinion, if you want to improve the names of the pages, you should propose a change in TechDraw's source code.

Being completely honest, I don't like the way wandererfan has named many of the tools in TechDraw. In my opinion, they should follow this convention, [Workbench]_[Tool], where [Tool] is a substantive that can be used as part of a sentence. This is done in the Draft Workbench, for example: Draft_Line, Draft_Polygon, Draft_Rectangle, Draft_Array, etc. Then in a regular sentence you can say, "please create a Draft Rectangle", and it is evident which workbench and object is meant.

In TechDraw, the names are more about actions, so they cannot be used in a sentence very well: TechDraw_New_Pick, TechDraw_NewView, TechDraw_NewActiveView, TechDraw_NewSection, etc.

I think these would be better as TechDraw_Pick, TechDraw_View, TechDraw_ActiveView, TechDraw_Section, etc.

----

About redirections, yes, you can use redirections of pages, however, this only really works well for English language pages. You need to consider translated pages.

For example, the page [TechDraw_Insert_New_Page_Using_Template] could be redirected to [TechDraw_New_Pick]. However, once the translation of that page is produced, you would have [TechDraw_Insert_New_Page_Using_Template/de] redirected to [TechDraw_New_Pick/de], however, the first redirection is not done automatically. This causes a problem with existing page names and existing translations.

So, in general, redirections should be kept to a minimum, in general, only when there are old pages that have been migrated to a new page. Why should a redirection be kept? Even if that link name is no longer used in the wiki, there may be links to the old name in the forum, so somebody who reads old threads in the forum may still want to follow those links.

----

In the past, NormandC was the one who monitored the wiki closely. If you edited something that he didn't like, he would call you an idiot and would publicly rant about how dumb you were for not discussing your changes before in the forum. He was particularly aggressive if you dared affect the translations. Angry little Quebecois he was; do not mess with the French, man. Since NormandC decided to step away, the situation is less tense now. You can do more changes to the wiki, and not expect a bunch of insults.

----

Personally, I would like to see all wiki pages edited in the style of the Draft Workbench. About a year ago, I basically re-wrote all pages from that workbench to more or less follow a standardized style. My intention was to continue with Arch and then TechDraw, since I was using those workbenches the most, and I felt the documentation was not very good. But due to time constraints, my constant clashes with Normand, and giving priority to other pages, I never quite followed through with my plan. I still would like to continue improving the pages, but now I'm also busy organizing the Draft code itself, so I haven't prioritized the documentation.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
User avatar
uwestoehr
Posts: 1792
Joined: Sun Jan 27, 2019 3:21 am

Re: [TechDraw] updating Wiki pages

Postby uwestoehr » Sat Nov 02, 2019 7:55 pm

vocx wrote:
Sat Nov 02, 2019 6:06 pm
The wiki pages should be named as the code shows in the sWhatsThis field....
Many thanks for your brief explanations. I will do so.

Concerning redirections, I think I should leave the page names as they are for now and focus on the content of the pages.

vocx wrote:
Sat Nov 02, 2019 6:06 pm
So, in my opinion, if you want to improve the names of the pages, you should propose a change in TechDraw's source code.
...
I think these would be better as TechDraw_Pick, TechDraw_View, TechDraw_ActiveView, TechDraw_Section, etc.
I can do so but would like to leave this of course to Wandererfan since it is his baby and a father should give the name ;-).

vocx wrote:
Sat Nov 02, 2019 6:06 pm
In the past, NormandC was the one who monitored the wiki closely...
Oh, that sounds really bad. I am glad that I could work in the Wiki without and problems.
renatorivo
Posts: 2611
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: [TechDraw] updating Wiki pages

Postby renatorivo » Sat Nov 02, 2019 11:23 pm

uwestoehr wrote:
Sat Nov 02, 2019 7:55 pm
vocx wrote: ↑
Sat Nov 02, 2019 6:06 pm
In the past, NormandC was the one who monitored the wiki closely...

Oh, that sounds really bad. I am glad that I could work in the Wiki without and problems.
Hi vocx, thanks for your contribution which is always very effective, but out of gratitude I have to say that NormandC taught me a lot.
I have been wrong many times, NormandC has always corrected me without insults. I am sorry that it is presented in a bad way.
At the beginning, his contribution was very important. Even if he abandoned, his score is still very high.
contributi.PNG
contributi.PNG (66.85 KiB) Viewed 578 times
This with friendship and collaboration.
Renato
vocx
Posts: 5206
Joined: Thu Oct 18, 2018 9:18 pm

Re: [TechDraw] updating Wiki pages

Postby vocx » Sun Nov 03, 2019 7:19 am

uwestoehr wrote:
Sat Nov 02, 2019 7:55 pm
Concerning redirections, I think I should leave the page names as they are for now and focus on the content of the pages.
Yes, the content is the most important. The name can always be changed later if needed.
I can do so but would like to leave this of course to Wandererfan since it is his baby and a father should give the name ;-).
Yeah, but it doesn't hurt to ask. Wandererfan is pretty receptive to good ideas.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
User avatar
wandererfan
Posts: 4078
Joined: Tue Nov 06, 2012 5:42 pm

Re: [TechDraw] updating Wiki pages

Postby wandererfan » Sun Nov 03, 2019 6:03 pm

uwestoehr wrote:
Sat Nov 02, 2019 7:55 pm
I can do so but would like to leave this of course to Wandererfan since it is his baby and a father should give the name ;-).
I'm uncle by adoption, not the father.

Changing the names has never made it to the top of my work queue. I just put up with the ones I don't like and distract myself by working on something else.

If you (or anybody else) want to make the names sensible and consistent, please go ahead.
User avatar
uwestoehr
Posts: 1792
Joined: Sun Jan 27, 2019 3:21 am

Re: [TechDraw] updating Wiki pages

Postby uwestoehr » Sun Nov 03, 2019 8:37 pm

vocx wrote:
Sat Nov 02, 2019 6:06 pm
they should follow this convention, [Workbench]_[Tool], where [Tool] is a substantive that can be used as part of a sentence
I spoke with wandererfan and he gave his go. So here is a patch that would do the renaming:
https://github.com/donovaly/FreeCAD/com ... c33e349aec

Please revise this and give feedback if this is OK, what is not OK, if you have better names in mind etc.

(Note the menu name changes might interfere with PR https://github.com/FreeCAD/FreeCAD/pull/2687 but I guess before we are ready with the name change this PR will have been merged and then I rebase.)