general discussion about Wiki rules, style guidelines etc.
Posted: Tue Jun 14, 2022 6:56 pm
Dear Wiki editors,
since I handle the releases I actively contacted people to get more feedback outside of my bubble. My aim is to listen what average and new users think. Besides this, I could introduce FC to some colleagues and see how they learn. In general the Wiki is used much, I also see that what is not well documented is not used (no matter if I e.g. showed them) - no surprise .
As a developer I force myself to improve the Wiki based in the feedback I got, when I think something is missing or too technical, etc. However I sometimes see that my changes are just reverted and that some Wiki maintainers are unhappy with it. In some private discussions with them, I hear that there are rules and the aim of this discussion is to unveil them.
The goal of this thread is therefore to discuss the existing Wiki pages where our Wiki principles are documented:
* https://wiki.freecadweb.org/GuiCommand_model
* https://wiki.freecadweb.org/WikiPages
I hope to get this way less frustration since then the info is available for everybody and by a discussion some things can be changed by the community.
Here are my 2 main points:
-----------------------------------
1. Let's focus on the readability and hide the technical terms to the sections where they belong to (scripting etc.)
Something I often heard is that the Wiki tries to be very correct with technical terms. For example in links we repeat the technical name. For example in the "See Also" fields of commands we repeat the prefix of the workbench. This was criticized since this is done in many links and gives the Wiki often a touch that one needs expert knowledge to learn commands. However unless you script with Python, users are not interested in knowing internal names. Just yesterday I had feedback that the prefix can even be confusing for average users. Note hereby that the techical feature names are given by developers and when they are "invented" one doe snot think about later documentation, how it would look in the Wiki, in YouTube videos or blog posts.
Let me give me two examples:
* First few days back we added pages for the Web workbench. On the main page:
https://wiki.freecadweb.org/Web_Workbench
we link the pages with user-friendly texts like "Set URL". People this way knows that the links page is obviously about setting an URL. If they need this, they can click the link. However in the different pages the situation is more technical. Take e.g. this page:
https://wiki.freecadweb.org/Web_OpenWebsite
In the Docnav the user reads "BrowserSetURL". This is technically of course correct, but why can't we just use "Set URL"? In the See Also field the users reads "Web BrowserSetURL", so even more technical. I think the user knows he reads about the web workbench, so also here the term "" would do the job in my opinion. (In cases where the workbench matters, it is of course sensible to have it as prefix to avoid confusion.)
* a user tried
https://wiki.freecadweb.org/Part_SectionCut
and asked why is it about Part. He cut assemblies and the parts in there were made using PartDesign. I explained him that the feature is technically implemented in the part workbench and he replied "why is this info important for any user? It works for different parts and assemblies, so just omit "Part".
-----------------------------------
2. Let's allow what MediakWiki allows us (math, figures etc.)
I like that we use MediaWiki, the same engine like the Wikipedia. Therefore new users might already know its syntax. Moreover the Wikipedia leads to continuous improvements in the MediaWiki software due to their massive user feedback. We should make more use of the features the engine provides us. For example there is a beautiful formula renderer and the formula syntax is the one of LaTeX. Therefore formulas can easily be created using one of the online LaTeX generators.
An Example: I once made a start in
https://wiki.freecadweb.org/B-Splines#Math
and I would like to transform more formulas and add new ones. It looks professional an I think sometimes a proper equation explains more than a long text.
-----------------------------------
I am curious to hear your opinion. many thanks in advance and regards
Uwe
@Roy_043 , @david69 , @mario52 , @renatorivo
since I handle the releases I actively contacted people to get more feedback outside of my bubble. My aim is to listen what average and new users think. Besides this, I could introduce FC to some colleagues and see how they learn. In general the Wiki is used much, I also see that what is not well documented is not used (no matter if I e.g. showed them) - no surprise .
As a developer I force myself to improve the Wiki based in the feedback I got, when I think something is missing or too technical, etc. However I sometimes see that my changes are just reverted and that some Wiki maintainers are unhappy with it. In some private discussions with them, I hear that there are rules and the aim of this discussion is to unveil them.
The goal of this thread is therefore to discuss the existing Wiki pages where our Wiki principles are documented:
* https://wiki.freecadweb.org/GuiCommand_model
* https://wiki.freecadweb.org/WikiPages
I hope to get this way less frustration since then the info is available for everybody and by a discussion some things can be changed by the community.
Here are my 2 main points:
-----------------------------------
1. Let's focus on the readability and hide the technical terms to the sections where they belong to (scripting etc.)
Something I often heard is that the Wiki tries to be very correct with technical terms. For example in links we repeat the technical name. For example in the "See Also" fields of commands we repeat the prefix of the workbench. This was criticized since this is done in many links and gives the Wiki often a touch that one needs expert knowledge to learn commands. However unless you script with Python, users are not interested in knowing internal names. Just yesterday I had feedback that the prefix can even be confusing for average users. Note hereby that the techical feature names are given by developers and when they are "invented" one doe snot think about later documentation, how it would look in the Wiki, in YouTube videos or blog posts.
Let me give me two examples:
* First few days back we added pages for the Web workbench. On the main page:
https://wiki.freecadweb.org/Web_Workbench
we link the pages with user-friendly texts like "Set URL". People this way knows that the links page is obviously about setting an URL. If they need this, they can click the link. However in the different pages the situation is more technical. Take e.g. this page:
https://wiki.freecadweb.org/Web_OpenWebsite
In the Docnav the user reads "BrowserSetURL". This is technically of course correct, but why can't we just use "Set URL"? In the See Also field the users reads "Web BrowserSetURL", so even more technical. I think the user knows he reads about the web workbench, so also here the term "" would do the job in my opinion. (In cases where the workbench matters, it is of course sensible to have it as prefix to avoid confusion.)
* a user tried
https://wiki.freecadweb.org/Part_SectionCut
and asked why is it about Part. He cut assemblies and the parts in there were made using PartDesign. I explained him that the feature is technically implemented in the part workbench and he replied "why is this info important for any user? It works for different parts and assemblies, so just omit "Part".
-----------------------------------
2. Let's allow what MediakWiki allows us (math, figures etc.)
I like that we use MediaWiki, the same engine like the Wikipedia. Therefore new users might already know its syntax. Moreover the Wikipedia leads to continuous improvements in the MediaWiki software due to their massive user feedback. We should make more use of the features the engine provides us. For example there is a beautiful formula renderer and the formula syntax is the one of LaTeX. Therefore formulas can easily be created using one of the online LaTeX generators.
An Example: I once made a start in
https://wiki.freecadweb.org/B-Splines#Math
and I would like to transform more formulas and add new ones. It looks professional an I think sometimes a proper equation explains more than a long text.
-----------------------------------
I am curious to hear your opinion. many thanks in advance and regards
Uwe
@Roy_043 , @david69 , @mario52 , @renatorivo