general discussion about Wiki rules, style guidelines etc.

Discussions about the wiki documentation of FreeCAD and its translation.
adrianinsaval
Veteran
Posts: 3080
Joined: Thu Apr 05, 2018 5:15 pm

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

Post by adrianinsaval »

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
I'm not sure if uwe's version is better but I have to say that the current format looks a lot like a list of steps rather than independent alternative methods, reading carefully clears this doubt quickly but it does introduce that doubt, at least to me, and it's not the first time I had that impression.
User avatar
Roy_043
Veteran
Posts: 5234
Joined: Thu Dec 27, 2018 12:28 pm

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

Post by Roy_043 »

adrianinsaval wrote: Wed Jun 15, 2022 6:00 pm the user facing name
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.
Last edited by Roy_043 on Wed Jun 15, 2022 8:45 pm, edited 1 time in total.
User avatar
Roy_043
Veteran
Posts: 5234
Joined: Thu Dec 27, 2018 12:28 pm

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

Post by Roy_043 »

adrianinsaval wrote: Wed Jun 15, 2022 6:10 pm reading carefully
I sort of expect that the information in the Wiki is read carefully. I would not be able to write a single sentence otherwise. :mrgreen:

The formatting of the Usage paragraph is simple: steps are numbered, options are bulleted. Not following that pattern for some pages is not an option IMO. We need more consistency not less.
User avatar
Roy_043
Veteran
Posts: 5234
Joined: Thu Dec 27, 2018 12:28 pm

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

Post by Roy_043 »

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.?
User avatar
Roy_043
Veteran
Posts: 5234
Joined: Thu Dec 27, 2018 12:28 pm

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

Post by Roy_043 »

adrianinsaval wrote: Wed Jun 15, 2022 6:00 pm the section cut feature is implemented in Part because it depends on Part functionality,
This is only semi valid. A lot of commands from the Draft WB depend on Part functionality, and yet they have the Draft prefix. And the Std_Import and Std_Export commands depend on code from many workbenches.
adrianinsaval
Veteran
Posts: 3080
Joined: Thu Apr 05, 2018 5:15 pm

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

Post by adrianinsaval »

My understanding is that the prefix is not about dependency but about were in the code it's implemented. Section cut is implemented in part because it depends on part and std is not allowed to depend on part, this is not the case for draft were most of it depends on part.
User avatar
Roy_043
Veteran
Posts: 5234
Joined: Thu Dec 27, 2018 12:28 pm

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

Post by Roy_043 »

We are going off topic, but, as already mention, Std_import and Std_Export do depend on Part and other workbenches.
User avatar
Roy_043
Veteran
Posts: 5234
Joined: Thu Dec 27, 2018 12:28 pm

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

Post by Roy_043 »

To move the discussion forward:

Here are some concerns, some already mentioned in the previous discussion, that I think need to be addressed:

How would you write a beginner's tutorial that uses the Draft_Rectangle, the Part_Extrude and the Std_ViewFitAll commands without using prefixes?

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?

How would you create SeeAlso links for Part_Import, Mesh_Import and the Import_Export page? Leaving out the prefix of one or both of the first pages would then be strange. But if the page belongs to the Part WB it would also be strange the write "Part Import" here and use only "Import" for the same command on other Part pages.

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")?
adrianinsaval
Veteran
Posts: 3080
Joined: Thu Apr 05, 2018 5:15 pm

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

Post by adrianinsaval »

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.
david69
Veteran
Posts: 1085
Joined: Wed Jan 01, 2014 7:48 pm

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

Post by david69 »

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.
Post Reply