general discussion about Wiki rules, style guidelines etc.

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

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

Post by Roy_043 »

@chrisb

In this case we see an editor take a layout that conforms to the GuiCommand_model and modify it in such a way that it no longer does. Uwe knows about the model, it has been pointed out several times (that is why the word 'unveil' in his initial post is so annoying, it completely misrepresents the facts). It has also been explained that it is effectively a consensus that was reached in the past and that it is therefore important to follow it. IMO it should be allowed to revert such an edit.

I'd also like to point out that nobody (including Uwe) consults previous editors before making changes to the Wiki. So the fact that he raised this point of etiquette here is dubious. There are also practical concerns. When f.e. marking 10 pages for translation it would be very problematic to have to start discussions with all editors involved. It is not exactly a 'fun' job as is.
Last edited by Roy_043 on Fri Jun 17, 2022 2:20 pm, edited 1 time in total.
User avatar
FBXL5
Posts: 305
Joined: Sat Aug 03, 2019 8:45 pm

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

Post by FBXL5 »

chrisb wrote: Fri Jun 17, 2022 12:51 pm
+1
User avatar
FBXL5
Posts: 305
Joined: Sat Aug 03, 2019 8:45 pm

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

Post by FBXL5 »

Roy_043 wrote: Fri Jun 17, 2022 2:17 pm IMO it should be allowed to revert such an edit.
It seems to be
chrisb wrote: Fri Jun 17, 2022 12:51 pm 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.
The discussion seems to have started with the reversion of an edit.
heda
Posts: 886
Joined: Sat Dec 12, 2015 5:49 pm

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

Post by heda »

this is really a thread that i should not comment on, do not have any skin in the game, but will cast my 2 cents any ways

imho in case of doubt, or one suspects one is about to make a controversial edit, one should sandbox the edit and raise it on the forum (or a wiki discussion page), can also make temp pages in sandbox, do not think anyone will object to that

regarding the latex, imho - fire away - there are online editors (or one can install a latex package, look at cheatsheets or whatever) if someone wants to spend the time to do proper math renderings, let them (several md parsers eat latex as well, as a side note i do not yet understand the benefits of moving to gh/md, but suppose there are some)

having the wb prefix is great for discoverability for scripting, i.e. just by looking at the page name one knows where to look in python to get the same (if it is available).

however it sucks for wiki discoverability since the wiki search function, or rather the searchbox completer only does exact matches (could it not be possible to tweak the search to be case insensitive), so for anyone searching in the box, they have to know that it is in part and remember to capitalize it to get the suggestion, the other way around would probably work, i.e. "import " and all possible "import " should show up (is at the same time an argument to have all small caps :-)

in other words, one could choose to put the "wb/source identifier" after the command name (on the wiki)...
not that I think that would make a command like "TechDraw_ExtensionShortenLine" easier to discover, the cmd name is a hilarious contradiction in terms... (by no means arguing for a name change on that - it simply is an edge case)

btw, was there not at some point in time a script that scraped source for commands, and generated the pages (empty) that did not exist?

at last, fc is a complicated machine with an abundance of edge cases, and imho if one does not know what to look for, or the search terms to find it, one will always be lost no matter what - to make it soft on fresh readers - having well authored introduction pages, or tutorials is really the only thing that works - getting new users quickly up to speed on the gotchas is key, and as any piece that has some sort of complexity to it, once one has spent some time with it, things are getting more familiar and one starts to overlook the shortcomings for newcomers, simply because for oneself it works, and there is some logic to what some perceive a complete mess - think that is hard to avoid for anything once that complexity threshold is surpassed
chrisb
Veteran
Posts: 43018
Joined: Tue Mar 17, 2015 9:14 am

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

Post by chrisb »

Roy_043 wrote: Fri Jun 17, 2022 2:17 pm In this case we see an editor take a layout that conforms to the GuiCommand_model and modify it in such a way that it no longer does. Uwe knows about the model, it has been pointed out several times (that is why the word 'unveil' in his initial post is so annoying, it completely misrepresents the facts). It has also been explained that it is effectively a consensus that was reached in the past and that it is therefore important to follow it. IMO it should be allowed to revert such an edit.
Following the title of this topic I tried to state a general rule, and I hope you can agree on it as such. From your explanations and not knowing the complete background and the history of the concrete case, I would rate it as one of the exceptions to the general rule.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
User avatar
Roy_043
Veteran
Posts: 5031
Joined: Thu Dec 27, 2018 12:28 pm

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

Post by Roy_043 »

@uwestoehr You have raised the issue of etiquette. This is not a trivial matter.

I have called you out on double standards. You need to respond to that.

You also need to respond to chrisb's suggestion regarding the new etiquette rules. They will be a big change for all editors, but certainly for you and me.
User avatar
FBXL5
Posts: 305
Joined: Sat Aug 03, 2019 8:45 pm

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

Post by FBXL5 »

Roy_043 wrote: Wed Jun 22, 2022 9:11 am
@Roy_043 I'm sorry. I didn't want to upset you. In the other thread I mentioned your name explicitly to give a hint who the last editor was. I Shouldn't have put it all in on sentence. :roll:
My First steps were indeed discouraging when someone else reverted my improvements on translations. (not your fault...)
When you corrected my attempts on the SheetMetal pages, I was a bit disappointed at first but then realised that it is better to learn from your corrections than to be angry about them. I fancy your improvements on the PartDesign pages related to pattern and dress-up features.

chrisb wrote: Fri Jun 17, 2022 12:51 pm 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.
I would rather say:
- It is allowed to add content to a wiki page without asking former authors.
- Removing content or reverting edits need at least an explanatory comment. A link to a discussion could be an option.

Who is the page maintainer? The one who adds some content or the one who "only" did the proofreading, the rearranging to meet the standards, and the marking for translation?
chrisb
Veteran
Posts: 43018
Joined: Tue Mar 17, 2015 9:14 am

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

Post by chrisb »

FBXL5 wrote: Wed Jun 22, 2022 12:52 pm I would rather say:
- It is allowed to add content to a wiki page without asking former authors.
- Removing content or reverting edits need at least an explanatory comment. A link to a discussion could be an option.
I like the idea of naming explicitely the adding of content. And we shouldn't try to specify this further, because we know that there isn't a sharp border between adding and editing.

My post was based on the idea of what I call "normal" human interaction, where it is a no go to destroy something which another person has created, often with considerable effort. So I would say we have three stages:

- adding is ok
- reverting must be discussed
- editing is something in between, probably "should be discussed"

And I want to make clear that this is a general rule where exceptions are possible.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
User avatar
FBXL5
Posts: 305
Joined: Sat Aug 03, 2019 8:45 pm

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

Post by FBXL5 »

I see a lot of discussion coming, resulting in less time for working on the pages. :?
Post Reply