Part Design Datum Plane wiki page name is wrong

[drmacro]

The Part Design Datum plane page is called Part Design Plane, then goes on to describe Datum Plane (very confusing when web searching Part Plane primitive)

I propose naming it Part Design Datum Plane.

This should be done for Part Design Datum Line as well.

[chrisb]

Aren't the wiki page names somehow linked to the names in the code, so that "What's this?" works correctly?

[drmacro]

maybe, but, maybe some thought needs go into that functionality.

Right now if you want tell a new (or even old) user to search on the web for "FreeCAD Part Design Datum Plane", you need to phrase it: "you need to read about Part Design Datum Planes, but search for Part Design Plane, there really isn't a Part Design Plane, but Part Design Datum plane is documented on a wiki page titled Part Design Plane, but that page really documents Part Design Datum Plane."
(yes I know one of the hits will be Part Design Plane, but, I'm pressing a point here...)

Same for Datum Line. Same for the wiki page titled Part Module, that goes on to document Part workbench.

Seems inconsistent, it's noticed as inconsistent by users.

And sure, with translations and limited doc writers, it's painful to fix...doesn't mean it shouldn't be sorted.

[Roy_043]

The solution for the mentioned PartDesign pages is relatively simple: Rename the command in the source code as well.

Renaming the Part_Module page, and others like it, will be an involved process. There are many links and references to these pages in the wiki. Yes: you can create a redirect, but in the end all them will have to be updated. Some of it can perhaps be automated (FuzzyBot?), but not all. The word 'module' cannot simply be replaced by 'workbench' whenever it occurs for example.

[drmacro]

The solution for the mentioned PartDesign pages is relatively simple: Rename the command in the source code as well.

This may be true, but, a bigger question is why is the user facing nomenclature different in so many cases. For example, from a user perspective, are they looking to find documentation on the Part module or the Part workbench? Is there a glossary in the wiki that explains "well, sometimes it's referred to as both...depending on if the conversation is with a developer or with a user".

A similar situation is seen in the forums all the time. The user is asking about XYZ and is referred to a url STD_XYZ.

Renaming the Part_Module page, and others like it, will be an involved process. There are many links and references to these pages in the wiki. Yes: you can create a redirect, but in the end all them will have to be updated. Some of it can perhaps be automated (FuzzyBot?), but not all. The word 'module' cannot simply be replaced by 'workbench' whenever it occurs for example.

Is painful or involved a good excuse for perpetuating confusing documentation?

[Roy_043]

good excuse

Let's not turn this into a debating contest. There is no Mars bar...

Many things can be improved regrading FreeCAD and its documentation. Programmers sometimes choose command names that are perhaps confusing for the average user. And the wiki can be lacking and inconsistent.

Regarding module vs. workbench: There are still editors who believe this distinction is important. But let's assume we convince them, and let's also assume that all others can be convinced that this is the way forward, are you personally willing to undertake the work? I estimate that this may involve 3-5 (very boring) days for each 'module' page we decide to rename.

[drmacro]

Let's not turn this into a debating contest. There is no Mars bar...

I'm not debating. In fact I'm just echoing what is heard in multiple forums and online media. For example, just yesterday it was asked: "is FreeCAD for developers? it seems the documentation is meant for programmers not users...".

Many things can be improved regrading FreeCAD and its documentation. Programmers sometimes choose command names that are perhaps confusing for the average user. And the wiki can be lacking and inconsistent.

It is pretty well known in programming circles, that programmers typically don't write documentation that is good for end users.

Regarding module vs. workbench: There are still editors who believe this distinction is important.

To them it may be important. To a new user? And that is my ultimate point, is the wiki for programmers or users? Maybe there needs to be a distinction and separation.

But let's assume we convince them, and let's also assume that all others can be convinced that this is the way forward as well, are you personally willing to undertake the work involved? I estimate that this may involve 3-5 (very boring) days for each 'module' page we decide to rename.

Well, I've hit this bump several times now, when I've looked at improving the wiki and discussed the changes. So, I've already spent some of that time...with no results, other than people telling me status quo is ok. So, sure, I can't sit here and bitch without being willing to do work.
As my long dead mother used to say: "S**t or get off the pot."

[chrisb]

The code is the way it is. And it is probably sensible to have prefixes as "Std_". To me the question is, if there is a possibility loosen the lock between the internal names and the documentation. I imagine something like a list of pairs such as [(internal1,external1), ...] such as [(PartDesign Plane,PartDesign DatumPlane), (PartDesign Module,PartDesign Workbench),(Std DependencyGraph,DependencyGraph),...], which is used when creating the "What's this?" information. The Algorithm would be to check the mapping first, and if the term isn't found on the left side, the old mechanism is taken, otherwise the procedure continues with the term on the right.

[Roy_043]

Doing away with the WB prefixes is not realistic IMO. F.e. you can create a line with the Part_Primitives command in the Part WB module. At some point a developer may want to create a separate command for this, as has been done with Part_Box etc. This would then not be possible if we were to rename 'Draft_line' to 'Line'.

The workbench concept does come with a certain level of complexity. I think it is this unavoidable complexity that explains a lot of the confusion that new users experience. An improved nomenclature will not change this significantly.