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!
User avatar
MSOlsen65
Posts: 226
Joined: Wed Feb 19, 2020 8:30 pm
Location: Winnipeg, MB Canada
Contact:

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

Post by MSOlsen65 »

DELETIONS OF DOCUMENTATION BELOW DEVELOPMENT VERSIONS

I have been reading and following this sub-forum for about two months now. In that time, I have noticed an apparent tendency to focus documentation nearly exclusively towards the development version. For example:
Draft: Remove obsolete tools?
Postby hmk » 17 Jul 2021 03:10
https://wiki.freecadweb.org/Draft_Module#Obsolete_tools

It seems to me all of these tools, except Array, are no longer available in 0.20 and should be removed?
The viewpoint indicated here is that the only version to consider is the Development version (currently v0.20) and ignores the fact that there exists a large group of Users relying on the Stable version (currently v0.19). This is not the only example, nor do I suggest it to be in anyway malicious. Rather it happens to be the most recent occurrence that appears to show a lack of User awareness.

The FreeCAD Documentation website's Main Page acknowledges three specific group of people -- Users, Power Users, and Developers, I will use these terms with the implied definitions provided by the Main Page. Hence new comers are automatically inlcuded among the Users. Finally I would note that these groups are, within any given topic area, linear ray progressive in nature (e.g. a person cannot be a Power User without first having been a User, and once a having progressed from one group to the next, they are not able to retrograde -- i.e. a Power User will never again innately have the limited perspective of a User for that particular topic).

Many Users are not able to make use of Development versions for any of a broad array of reasons. Thus deleting documentation simply because it does not relate to the Development versions is highly detrimental to Users. Such actions have been, and continue to be, understandably perceived by Users as contemptuous of Users, even though such is not the intent. Therefore, I should like to make the following suggestion as a means to resolve this perception while providing for the needs of all -- those using the Stable Version and those using the Development Versions.

According to the official website, v.0.19 is the current Stable Version. Only the current Stable Version should be used to determine deletions, and not the Development Versions.The Development Versions should be used to make additions (new pages) or parenthetical changes (i.e. the change unique to v0.20 is added in parenthesis while the content of the v0.19 information remains unchanged) only. This allows the documentation to remain relevant for both the Stable (current) and Development (future) versions. Again, Users are far more likely to run the Stable version and thus have need of its "complete" documentation.

If something is no longer available in the development versions, the parenthetical statement should read something like, "(deleted / deprecated in Development Version vX.X.x)". If this statement is added to the page title, it makes finding and archiving / deleting such pages relatively simple when version X.X.x officially becomes the stable version. It also provides immediate historical context (especially helpful for archived documentation).

I personally recommend archiving rather than deleting, as an archive is useful for those working with older versions and provides historical perspective and "corporate memory" information useful to Developers, and possibly Power Users, for future advancements. After all, it is a well proven axiom that "Those who ignore the past, are doomed to repeat the past." So having the archives becomes a benefit.

It is important to remember that the purpose of any documentation is to provide others the knowledge they need to make use of both the Stable and Development versions without, or at least with highly minimized, outside assistance. After all, that is why people are encouraged to search the forum before asking a question.

As the future of FreeCAD is entirely dependent upon Users progressing to Power Users and Developers, it is paramount to ensure they have the best and most successful experience possible. This way we actively encourage their growth into contributing Power Users, Developers, and supporters (Translators, Tutors, etc.). As FreeCAD is always asking for more help, failing to encourage and mentor our Users is in fact actively working against our own best interests .
Last edited by MSOlsen65 on Thu Nov 17, 2022 9:48 pm, edited 2 times in total.
Sincerely,


Michael S. Olsen
Electrical Engineer & Joiner
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 »

DISPARITY BETWEEN THE GUI AND THE WIKI DOCUMENTATION

The issue as I understand it is this:

Currently, Users spend a inordinate amount of time looking for what they see in the GUI (often quite different from the source code), only to find much of the documentation they need effectively hidden from them because the documents have been arranged by source code. From the User's perspective nothing appears to exist that effectively bridges this gap. Thus from the User's perspective large portions of the documentation simply do not exist.

The Main Page of the wiki describes the User hub as:
Screenshot 2021-07-20 at 08-53-13 FreeCAD Documentation.png
Screenshot 2021-07-20 at 08-53-13 FreeCAD Documentation.png (22.61 KiB) Viewed 4321 times
Main Page#The Hubs

For any documentation aimed at Users, all buttons, commands, tools, etc. literally needs to reflect exactly what the User sees in the GUI (not the source code) . The reasons for this are as follows:
  1. The GUI is the only universal point of reference available to all Users.
  2. A User does not yet have the knowledge necessary to relate what they see in the GUI to what is written in the source code.
  3. Since computers are known to be exceptionally pedantic, Users generally ignore results that differ from exactly what is given in the GUI (in virtually all other application programs any variance is in fact a different command).
Think of a thesaurus, one looks for a word they already have. Once found, then and only then, are synonyms and antonyms listed with their correspondingly relative definitions. To a User, source code is an unknown (and in most applications unknowable) synonym.

To resolve this issue, I would suggest a compromise. Keep the code, but make it a parenthetical statement following the literal GUI "button". Here is an example of the issue and a solution (User Hub#Workbenches):

ISSUE:
Screenshot 2021-07-20 at 09-23-42 (1) GuiCommand model Wiki page - Page 6 - FreeCAD Forum.png
Screenshot 2021-07-20 at 09-23-42 (1) GuiCommand model Wiki page - Page 6 - FreeCAD Forum.png (21.9 KiB) Viewed 4321 times

The "Std Base" is not found anywhere in the GUI; so to a User, this entry is meaningless until explained by someone in the forum or elsewhere (i.e. it may as well not be there). Yet if we change the listing slightly:

SOLUTION
Screenshot 2021-07-20 at 09-23-59 (1) GuiCommand model Wiki page - Page 6 - FreeCAD Forum.png
Screenshot 2021-07-20 at 09-23-59 (1) GuiCommand model Wiki page - Page 6 - FreeCAD Forum.png (23.41 KiB) Viewed 4321 times

This keeps the documentation's current organizational convention of Std Base, but now makes it immediately meaningful to the User by directly relating it to common terminology that the User already knows from the GUI or from conventional norms of application programs in general. This change makes it possible for Users to find what they are looking for based upon what they are given by the GUI; it provides Users and example of internal naming conventions; and finally, it does not require any link or other changes that would negatively effect current organizational or structural standards while simultaneously making GUI tools and commands far more searchable for Users-- and as a result everyone else. It would also mean that some (if not many) "redirect" pages may in fact become unnecessary thanks to highly increased uniformity between GUI and wiki.

P.S. I did this simply as a "Preview" and then cancelled the edit so that no actual change was made to the documentation. If my suggestion is approved, I would be happy to make these edits my "first assignment".
Sincerely,


Michael S. Olsen
Electrical Engineer & Joiner
david69
Veteran
Posts: 1774
Joined: Wed Jan 01, 2014 7:48 pm

Re: Concerns From a User's Perspective

Post by david69 »

The viewpoint indicated here is that the only version to consider is the Development version (currently v0.20) and ignores the fact that there exists a large group of Users relying on the Stable version (currently v0.19).
it's unfortunately a limitation of the wiki as it is today and also numbers of active members. i am only a translator not even a user for ex.
I raised this point couple months ago when we were between 0.18 and 0.19 and that was the given reasons and ... i must say we need to live with except if somebody find a smart way, or a good platform and enough hands. if you give a look to what LibreOffice or Blender offer, that's an other level.

why 0.20 than 0.19? A choice was made.

by the way, your solution fits.
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 »

david69 wrote: Wed Jul 21, 2021 8:43 pm it's unfortunately a limitation of the wiki as it is today and also numbers of active members. i am only a translator not even a user for ex.
WOW! you don't even use the software and you know that a problem exists. That is quite the condemnation of the current system. :shock:

I raised this point couple months ago when we were between 0.18 and 0.19 and that was the given reasons ...
I have also been told the same, but that does not make it a good argument. It means that a very large portion of Users are effectively denied the basic support they need. Somehow we must preserve the information for the current Stable version while simultaneously writing for the future Development versions.

... if you give a look to what LibreOffice or Blender offer, that's an other level.
I agree. OpenOffice (predecessor to LibreOffice) split their docs group into 3 teams: Current, Future, and Proof Readers. The Current team was the smallest and had two main functions -- correct errata in the docs for the current (stable) version and conduct the merging when a new (development) version was released as stable. The future team was the largest. they wrote the actual docs (only changes and additions needed writing while deletions were struck through with a single line). A few were also available to answer questions for the Current team during the merge operations. The Proof Readers were the major support to the Current team during merger. After, most of the Proof Readers time was spent with the Future team. This kept errata to a minimum and greatly simplified the Current team's work load.

by the way, your solution fits.
Thanks. I presume you meant "works" instead of "fits." English is at best a clumsy language. :lol: I based it off of the IBM model for digitally writing their User Manuals. It is an efficient and well proven method requiring minimal staffing and effort.
Last edited by MSOlsen65 on Wed Jul 21, 2021 10:25 pm, edited 1 time in total.
Sincerely,


Michael S. Olsen
Electrical Engineer & Joiner
david69
Veteran
Posts: 1774
Joined: Wed Jan 01, 2014 7:48 pm

Re: Concerns From a User's Perspective

Post by david69 »

jump on the boat. two more hands will not be enough and with your experience, the boat will go a bit further.
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 »

david69 wrote: Wed Jul 21, 2021 10:04 pm jump on the boat. two more hands will not be enough and with your experience, the boat will go a bit further.
Already done. I now have Editor privileges. All I now need is some "work."

I am mentioning my concerns here so that any changes can be agreed upon before they are executed. My intent is to gain a consensus so that the hard work already accomplished is not undone by accident. Those already working on the docs, may well foresee issues I currently cannot, and these must be taken into account before making changes.
Sincerely,


Michael S. Olsen
Electrical Engineer & Joiner
hmk
Posts: 159
Joined: Tue Sep 29, 2020 1:19 pm
Location: Berlin, Germany

Re: Concerns From a User's Perspective

Post by hmk »

MSOlsen65 wrote: Wed Jul 21, 2021 10:37 pm Already done. I now have Editor privileges. All I now need is some "work."
I would consider myself an advanced novice. I jumped into editing the Wiki because I think the documentation is most value for beginners and since I am reading it with a beginner' mindset I hope that I can spot problems better compared to expert users.

I would say:
* While learning FreeCAD always check the documentation with an eye on possible improvements. Address problems right away, don't wait.
* Start with small edits (typos, sentence-level). For example fix formatting: https://wiki.freecadweb.org/index.php?t ... did=851839
* Check out GuiCommand_model
* If you change a command, make sure you do not break consistency with other commands in the same workbench. (Check, say, 5 commands, you may find a common pattern and probably also see variations that violate the editing guidelines.)
* Write a (Git-style) log message what you did. (The log message could easily be longer than the actual edit.). Commit many small changes rather than doing a bulk commit that addresses different problems. This is actually my style, not generally accepted!
* Try to follow the existing guidelines even if if you think you know better. But push the envelope a bit if you hit a case that does not fit the guidelines or is not covered by them :)
* Try not to get frustrated if (senior) editors (immediately) "correct" your actions. Nobody has bad intentions and it's a learning experience for everybody...
* Have fun!
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 »

hmk wrote: Thu Jul 22, 2021 10:51 am ...
I would say:
* While learning FreeCAD always check the documentation with an eye on possible improvements. Address problems right away, don't wait.
* Start with small edits (typos, sentence-level). For example fix formatting: https://wiki.freecadweb.org/index.php?t ... did=851839
...
* Try to follow the existing guidelines even if if you think you know better. But push the envelope a bit if you hit a case that does not fit the guidelines or is not covered by them :)
* Try not to get frustrated if (senior) editors (immediately) "correct" your actions. Nobody has bad intentions and it's a learning experience for everybody...
* Have fun!
Thanks for some very good advice. :D

The questions now are:
  1. What are your thoughts about the two concerns addressed in the two Original posts -- DELETIONS OF DOCUMENTATION BELOW DEVELOPMENT VERSIONS, and DISPARITY BETWEEN THE GUI AND THE WIKI DOCUMENTATION? :?: :?:
  2. Are my assessments of the issues reasonable, and if not why?
  3. Assuming the assessment is reasonable, are my suggestions clear in content, context and scope?
  4. Would these suggestions be workable, why or why not?
  5. Do any points of the suggestions actually violate the purpose of any current standard? If so explain.
  6. Barring a significant functional problem (i.e. these changes would cause broken links, etc.), what additional reasons exist to dismiss the suggestions?
These questions all for meaningful discussion on improvements that, though subtle, have the potential to make the documentation far more User friendly, and as such friendlier to all! It is not a matter of focusing solely on Users, but rather a matter of recognizing that everyone begins as a User. Also, when someone delves into what for them is a new topic, they could easily be seen as again being at the User level, thus anything that helps a User, help everyone. :mrgreen:
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 »

if you can come up with a versioning scheme for the wiki that is acceptable, suppose that is the answer to your concerns...
the wiki: moving from 0.18 to 0.19
that could include reinvestigate the powers of mediawiki...

personally I do not mind that the code structure shines through on the wiki,
sure it takes a while to learn what one should use as general starting points to find what one is after - but what does not here in the world.

it might be more bang for the buck to write a new wiki-page with a name like "how to navigate the wiki" and make that the starting page rather than the current "getting started"

I have never had any issues in finding a command from the gui (including the std ones...), but one wonders a bit how one actually finds pages that are not commands or tutorials, and there are plenty of those around with useful info (I think at least...).

I think the only way around that is to introduce "entry pages" somehow, sort of symbolizing a true table of content, which at least I am unaware of how to list on the wiki, the only way I think one can get hold of a list of all pages (not entirely polluted with language pages) is to scrape the whole website (which I assume is not something that is encouraged as such).

something that possibly could help was if the whole wiki-database was available as a download so one could analyse it offline, possibly that could allow for simpler schemes to make for example search/replace tasks or similar (like redirect schemes etc).
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,

Thanks for a number of interesting comments. However I noticed that none of your comments actually address the issues or my suggested solutions. You also avoided the list of 6 specific questions immediately prior to your post. Instead, the overall tone of your comments can be reduced to a polite "Who cares" dismissal of the concerns.

I do not believe this was your intent as you took the time to include a specific link, and spent considerable effort to put forth your opinion. So I would ask that you kindly review the concerns a bit more carefully. Please consider specifying what points of which issue you are addressing, or as I did in the opening posts, separate your points into 2 separate post -- one for each issue. Finally, I would be happy to hear any of your concerns, keeping in mind that such concerns must be valid from the Perspective of a User, as opposed to a Power User or Developer, for that is the entire point of this discussion.
Sincerely,


Michael S. Olsen
Electrical Engineer & Joiner
Post Reply