general discussion about Wiki rules, style guidelines etc.

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
Roy_043
Veteran
Posts: 8450
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: 979
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: 979
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
Veteran
Posts: 1348
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: 53930
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: 8450
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: 979
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: 53930
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: 979
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. :?
User avatar
uwestoehr
Veteran
Posts: 4961
Joined: Sun Jan 27, 2019 3:21 am
Location: Germany
Contact:

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

Post by uwestoehr »

@Roy_043 , @chrisb and all other commenters, at first sorry for the delay. The post release time was much more work than the pre release time for me - tons of citations in the forum, GitHub and mail, mails, mails. However, feedback is welcome and Feedback was why I started this thread.

Let me make precise proposals to step forward:

- in https://wiki.freecadweb.org/GuiCommand_model#Usage we change the first point so that the obvious call of a command can also be described in one sentence. This would fix the criticism about treating users as kind of general computer beginners and this particular case was even mentioned explicitly more than once in feedback I got.

- in the DocNav (bottom/top navigation bar), we allow to use a short command name, not the exact technical name. For example in the FEM WB we already use in the DocNav "Elasticity equation" and not the technical term "EquationElasticity".
Note hereby that my aim is to allow things, not to force them. Those who do the work, should have some freedom. For example when you are working a lot with the Draft WB and thus get feedback about Draft, you have a good idea of a suitable naming.

- in the field "See also" in GuiCommand_model, we can use the same short command name we use in the DocNav, there is no need that the user must read the full technical name since he will see this after clicking on the link.

- in general links to commands can but don't have to have the full technical name in the link text. So depending on if it is necessary, we can have there the WB prefix or not

- also in general, a formatting allowed by the Wiki software is allowed. Only when a formatting would prevent translations or is too large to be read with smaller screens, we should step in.
The rationale behind this is that I want to make the Wiki work more attractive. E.g. adding images is a lot of work for beginners since one needs to read in advance. The cool thing is that we use the same Wiki engine as the Wikipedia and developers told me that they just copy Wiki syntax from the Wikipedia. This is very good because having info at all about a feature is better than not having it.
Sooner or later someone will edit the page anyway.

I think not much more needs to be done for now. Criticism about "too technical" wording can mean much and I therefore asked back what precisely we could do. My proposals are the result.

-------------------

Concerning the reversion of changes, we cannot expect users to read all our guidelines. So when someone makes a change that it not according to e.g. GuiCommand_model, we should write him. If this leads to a further discussion in the forum, fine. Discussing here means the user has a longterm interest in the Wiki work and does not pop up and then goes. If a new user does not react, we can adapt his change according to our guidelines.

I often heared from people (especially developers) that editing the Wiki is too complicated, one has to learn the syntax and there are many rules. This is true, therefore I am happy when people can just "hack-in" a description of a new feature or info at all. And afterwards the Wiki team beautifies the pages with proper templates, links etc. During the 0.19 and 0.20 release cycles I contacted several developers to write something to the Wiki and in the end I nevertheless found myself in documenting new features. I hope to reduce these cases bit by bit.
Post Reply