Concerns From a User's Perspective [Resolved & "In-Progrss]

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: Concerns From a User's Perspective

Post by heda »

aha, you noticed :-)
it was in contrary to you belief intentional to not directly engage in the topic,
but rather an (so far failed) attempt to hint in a different direction, like hmk.

I did not put in the phrase "it is easier to ask for forgiveness than approval" earlier, but that is probably how it is.

the way I see it (and please bear in mind that I have zero say on what happens on the wiki)...
you will not be able to get someone else to change the structure/function of the wiki by attempting to get agreements on the forum.
better to spend the time on actual edits to the wiki (which may or may not be rejected by the admins once they are done).

if this is to happen the way you intend, you need do & lead the actual change, and for that I assume that you need to have admin rights on the wiki (and probably start doing coding changes as well).
and if you reached a level of admin rights (where I suppose the first steps are like hmk listed, and a lot of time...), you probably have the answer to most of your questions (that you put forward)

btw, it is not that I do not care, but for me it boils down to what one can get done or not as persistent change (not so much what is ideal/perfect or not), thus I simply choose to spend my time on things that I judge have a reasonable path to an actual persistent change within a reasonable time period, if not I ditch it for time being and move on to something else.

what I do care about, in general, is that the people that want to contribute find their way into contributions that are accepted,
however having been on the forum for a while - one can conclude that this is not always the actual outcome...

I hope you will find your way to successful contributions.
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: Concerns From a User's Perspective

Post by heda »

something that I was not aware of it's existence until yesterday...

maybe you would find it worthwhile to update these to v0.19, which has quite some additions in relation to v0.18.
just a mere guess, but don't think the earlier author will make new versions.

0.18 Quick Reference Guides Are Released

just a suggestion.

in a perfect world, the generation of this would be scripted, and also including the tooltip text from the gui.
and of course be part of every release.

ps:
if one made a html version, that could be included in fc itself, and could hold "translation table" between gui names and wiki-page names as well,
in other words - it is a path to have a scrollable list of commands in the gui that can hold links to the underlying wiki pages...
User avatar
MSOlsen65
Posts: 226
Joined: Wed Feb 19, 2020 8:30 pm
Location: Winnipeg, MB Canada
Contact:

Re: Concerns From a User's Perspective

Post by MSOlsen65 »

heda wrote: Sun Jul 25, 2021 3:40 pm maybe you would find it worthwhile to update these to v0.19, which has quite some additions in relation to v0.18.
j...
0.18 Quick Reference Guides Are Released
...
if one made a html version, that could be included in fc itself, and could hold "translation table" between gui names and wiki-page names as well, in other words - it is a path to have a scrollable list of commands in the gui that can hold links to the underlying wiki pages...
I most wonderful list of suggestions! :idea: :D
I shall add them to my now growing list of content improvements. While HTML is not a problem, i have multiple WYSISYG writers that are excellent at converting text, I am not proficient with the FC source code. So direct inlcusion into FC is not yet practical. However, that doesn't mean I can't study up and learn. :mrgreen: :ugeek:

All that said, I very much appreciate your strong and helpful encouragements. I can be the most dense person in the room, so I often miss what others are hinting at. :oops: With myself, it is always best to be a bit more direct. Asking "Have you though of ...", or something similar generally works better than hinting. Like I said, I can tend to be a bit dense. Once I understand your intent, then I generally tend to track your thinking. So again, thank you. :D
Sincerely,


Michael S. Olsen
Electrical Engineer & Joiner
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: Concerns From a User's Perspective

Post by heda »

no worries - as a matter of fact there are people around that would call me dense at times as well :-)
User avatar
Roy_043
Veteran
Posts: 8450
Joined: Thu Dec 27, 2018 12:28 pm

Re: Concerns From a User's Perspective

Post by Roy_043 »

MSOlsen65 wrote:
I see that you have been working hard on quite a few wiki pages over the past days. It may be wise to take a break and give the wiki community some time to comment.

See for example:
Std_View_Menu
User avatar
MSOlsen65
Posts: 226
Joined: Wed Feb 19, 2020 8:30 pm
Location: Winnipeg, MB Canada
Contact:

Re: Concerns From a User's Perspective

Post by MSOlsen65 »

Roy_043 wrote: Sun Aug 01, 2021 11:24 am I see that you have been working hard on quite a few wiki pages over the past days. It may be wise to take a break and give the wiki community some time to comment.
Thanks for the compliment and for the recommendation. I have also followed up on heda's suggestion on the "Quick Reference Guides". I have downloaded the ODF versions and sent a response to bejant to confirm his intentions regarding their maintenance (i.e. will he be doing the updates & may I help or take over). So while I version on my downloads, I can give the Wiki a break.

I do know that some sort of "Intro" should be made explaining that the GUI command in is bold followed by the source code in parenthesis. I'm just not sure quite how to phrase it and where it should be placed on the overall Wiki. I'm thinking it should go on the User Hub home page, but I would like some input on this matter as there are several schools of thought, and I am not certain what would be best.
Sincerely,


Michael S. Olsen
Electrical Engineer & Joiner
User avatar
Roy_043
Veteran
Posts: 8450
Joined: Thu Dec 27, 2018 12:28 pm

Re: Concerns From a User's Perspective

Post by Roy_043 »

Full disclosure: In the case of these pages I am biased: I have spent a lot of time on the 'Std' pages last year, adding missing pages, bringing (sometime very old) pages up to date, and trying to make that set of pages look consistent. To do that I have embraced the existing standards.

Your work clearly breaks with those standards. Sometimes deliberately, sometimes unintentionally because you have not yet read the relevant information. If this is accepted it will mean a new standard that will have a big impact on all the pages that document the workbenches and their commands. As you may have guessed already, I am not in favor of adopting a new standard.

And IMO the changes you have made are not an improvement. The pages look messy, and confusing. The URL information you have added is distracting. Furthermore it is already available in the previous versions. All the user has to do is hover over a link. See image. Can you explain why this is not enough for you?

The previous versions of these index-type pages contain lists (words and images) that actually match what the user sees in the GUI. IOW there is no disparity between the GUI and the Wiki. So there in no reason to change them in the context of your 2nd concern. Why have you changed them anyway?
Attachments
wiki-url-already-available.png
wiki-url-already-available.png (22.37 KiB) Viewed 2886 times
User avatar
MSOlsen65
Posts: 226
Joined: Wed Feb 19, 2020 8:30 pm
Location: Winnipeg, MB Canada
Contact:

Re: Concerns From a User's Perspective

Post by MSOlsen65 »

Roy_043 wrote: Mon Aug 02, 2021 7:46 am Full disclosure: In the case of these pages I am biased: I have spent a lot of time on the 'Std' pages last year, adding missing pages, bringing (sometime very old) pages up to date, and trying to make that set of pages look consistent. To do that I have embraced the existing standards.
Firstly, thank you for all your hard work! It is immense in scope and impressive in quality. I am especially impressed with the work you have done on the "Std" pages. Overall, they are a major improvement.

Your work clearly breaks with those standards. Sometimes deliberately, sometimes unintentionally because you have not yet read the relevant information. If this is accepted it will mean a new standard that will have a big impact on all the pages that document the workbenches and their commands. As you may have guessed already, I am not in favor of adopting a new standard.
You are quite correct that what I have done does deviate from the current standards, and that if accepted, will bring about a change of standards. That said, any standard is merely a convention of consensus. It should be open to discussion and amendment over time to better reflect the needs and desires of those it serves. As change is rarely easy or comfortable, I would also agree that a well established standard, "should not be changed for light and transient reasons" -- Thomas Jefferson 1776. As such, I must apologize for what to you must appear to be just that.

Please understand that no disrespect is intended. Quite the contrary, I am honored that we are having a civil discourse, and gratefully welcome your input and insight. After all, I believe both our intents are clarity and improvement, and to that end cooperation, mutual respect, and understanding are proven best practices.

And IMO the changes you have made are not an improvement. The pages look messy, and confusing. The URL information you have added is distracting. ...Can you explain why this is not enough for you?
It was simply a means to explore a possibility: simultaneously providing both what the User sees in the GUI, and parenthetically, the source code commonly referred to throughout the documentation and the forum. Thus hoping to both facilitate a User's learning, and provide for the desires of Power Users and Developers. I do agree that some aspects do look messy and confusing. This is why I am grateful for you input. I believe together, the goals of improved clarity, uniformity of content between Wiki & GUI, and visual aesthetics can be achieved.

I do find it unfortunate that it has taken a brute force effort to bring about an actual discussion. When starting this thread, I had hoped to avoid such brute force, and the very real and personal hurt feelings that result from such efforts. Sadly, virtually none of the discussion was on point. Some of it being typically dismissive. So, It was with a disheartened resignation that I made those changes. It is also with renewed hope that I am responding to your post. I truly do wish to make FreeCAD better for everyone.

The previous versions of these index-type pages contain lists (words and images) that actually match what the user sees in the GUI. IOW there is no disparity between the GUI and the Wiki. So there in no reason to change them in the context of your 2nd concern. Why have you changed them anyway?
IOW :?: :?: :?:

Sorry, but I am not familiar with this TLA (3 letter abbreviation).

Concerning changes to GUI commands: If what was listed was in fact identical to the GUI, the only changes I intended to make where stylistic to provide a more uniform appearance across the page. Where the source code differed from the listing, it was included parenthetically following the command, again for uniformity of content. If I have made additional content changes, they were in fact unintentional, and for that I most sincerely apologize.

I truly wish to help and to improve what we already have. Your guidance and insights would go a long way towards that goal, and I would genuinely be grateful for them. Please let us continue to cooperatively build a "better" Wiki.
Sincerely,


Michael S. Olsen
Electrical Engineer & Joiner
User avatar
Roy_043
Veteran
Posts: 8450
Joined: Thu Dec 27, 2018 12:28 pm

Re: Concerns From a User's Perspective

Post by Roy_043 »

MSOlsen65 wrote: Mon Aug 02, 2021 1:24 pm the only changes I intended to make where stylistic to provide a more uniform appearance across the page.
The pages were very uniform and consistent before, and also consistent with similar pages belonging to other workbenches.

I may have missed something, but it seems to me that this is not well thought out:
You have started from what you call a gap between the GUI and the wiki.
The pages you have changed matched the menu structure in the GUI. So effectively there was no gap.
Now that I have pointed that out you are talking about stylistic issues, which did not exist either.
And the information you have added was already available (the user can hover or click the link).

At this point I am unconvinced. I see no pros, and quite a few cons.

Note 1:
For experiments like this you really should use sandbox pages.

Note 2:
Your forum messages are rather verbose. If in anyway possible try to be more concise.

Note 3:
To find the meaning of IOW you can just use a search engine.
chrisb
Veteran
Posts: 53930
Joined: Tue Mar 17, 2015 9:14 am

Re: Concerns From a User's Perspective

Post by chrisb »

Roy_043 wrote: Mon Aug 02, 2021 3:27 pm Note 2:
Your forum messages are rather verbose. If in anyway possible try to be more concise.

Note 3:
To find the meaning of IOW you can just use a search engine.
Conciseness is good. But it shouldn't go so far that the text needs a search engine to be understandable.
The first hit for IOW is "Isle Of Wight", the 2nd is "In Other Words", third is "Input Output Write". I guess you didn't mean Isle of Wight. Please note that there are many non native English speaking members visiting the English forum, and we don't have as much language redundancy as native speakers.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
Post Reply