Wiki:Discussion usage

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
manos
Posts: 432
Joined: Thu Nov 12, 2020 10:48 am
Location: Greece

Re: Wiki:Discussion usage

Post by manos »

onekk wrote: Thu Jun 16, 2022 1:20 pm
manos wrote: Thu Jun 16, 2022 12:53 pm ... There are plenty of pages with ambiguous terms.
Yes I agree, but see the following:
manos wrote: Thu Jun 16, 2022 12:53 pm What is Part ? The Workbench , an object or the container created with Std Part ?
This is more about a "disambiguation page" like in wikipedia, or maybe on some "Modelling guide" or even in an "Introductory Page"
I am afraid that speaking about ambiguity it is me who writes the most ambiguous texts: When I refer to unclear words I do not mean that their meanings are unknown. I mean that their meaning at that particular line in this Wiki:page is unclear-ambiguous. In other words when the user reads Part it is not clear if he means the Workbench Part or an object created by Part Workbench or the Std Part command which creates the container of bodies.


manos wrote: Thu Jun 16, 2022 12:53 pm The origin is referred to that of the body , or the Global origin etc,etc ? E.g. Placement and Attachment commands are full of indefinite terms.
onekk wrote: Thu Jun 16, 2022 1:20 pm Same as Above, but note that, a Glossary page will be useful.

https://wiki.freecadweb.org/Basic_Attachment_Tutorial
A note would help to determine the reference of the Origin .etc etc.
This is a constructive post, and I hope with some argumented answers, if this could seems offensive or polemic, sorry it was not my intention.
Not polemic at all. Thanks for the contribution.
User avatar
onekk
Veteran
Posts: 6098
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Wiki:Discussion usage

Post by onekk »

I admit that Part is not the best choice, but not for Part WB that is the core of FC.

Other objects are ambigius and even Part Design is not the hest choice.

But the problem is to remain on topic is that:

1) better documentation is needed but is improving.
2) adding notes as a tab is not clever way as it is add complexity even in the optics of maintainability.
3) discuting about a way of improving documentation is not a sin.

Some things are moving as in latest times something is moving.

Wait sometime and probably you will see some improvement, from what I know from other discussion on some threads.

If you want to collaborate it will be a good thing to signal where things are ambiguous and maybe open a discussion about this topic on the documentation thread (now I'm on mobile so no link sorry)

Regards.

Carlo D.
GitHub page: https://github.com/onekk/freecad-doc.
- In deep articles on FreeCAD.
- Learning how to model with scripting.
- Various other stuffs.

Blog: https://okkmkblog.wordpress.com/
manos
Posts: 432
Joined: Thu Nov 12, 2020 10:48 am
Location: Greece

Re: Wiki:Discussion usage

Post by manos »

adrianinsaval wrote: Thu Jun 16, 2022 1:52 pm
manos wrote: Thu Jun 16, 2022 12:53 pm Also this tab will help maintainers locate points of possible corrections and additions to the main page text.
I think the idea of a "Notes" tab to every page, it is a step to a more "decent documentation" and it is worthy of consideration.
It is better and more maintainable to add a Notes section in the wiki as it's done in many pages already, and some actually link to forum discussions when appropriate.
Where are the Notes section ,can you give an example ?
The see also section is also useful if you want to clarify stuff and normally when Part and other ambiguous terms are mentioned it is specified and linked to the corresponding page were it's explained, and even the icon is displayed.
[/quote]
What about "also section" . An example ?
Thanks for infos and ideas adraninsaval.
User avatar
Roy_043
Veteran
Posts: 8410
Joined: Thu Dec 27, 2018 12:28 pm

Re: Wiki:Discussion usage

Post by Roy_043 »

@manos Your suggestion is not practical. We simply can't do this. We do not have the human resources to monitor this. And there is also the proposed transition of the documentation to GitHub which is another reason to not do this.
manos
Posts: 432
Joined: Thu Nov 12, 2020 10:48 am
Location: Greece

Re: Wiki:Discussion usage

Post by manos »

Roy_043 wrote: Thu Jun 16, 2022 7:18 pm @manos ...We do not have the human resources to monitor this...
My idea does not comprise any monitoring. In contrary "Notes" mainly will be the conclusions from (monitored) forum.
Roy_043 wrote: Thu Jun 16, 2022 7:18 pm And there is also the proposed transition of the documentation to GitHub ....
A rather nightmare idea: Make the simple: Wiki complicated: Github
User avatar
FBXL5
Posts: 957
Joined: Sat Aug 03, 2019 8:45 pm

Re: Wiki:Discussion usage

Post by FBXL5 »

Roy_043 wrote: Thu Jun 16, 2022 7:18 pm And there is also the proposed transition of the documentation to GitHub...
I had a look at the GitHub wiki and so far it's not my cup of tea. It does neither invite to use nor to edit. :(
User avatar
onekk
Veteran
Posts: 6098
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Wiki:Discussion usage

Post by onekk »

FBXL5 wrote: Fri Jun 17, 2022 8:49 am I had a look at the GitHub wiki and so far it's not my cup of tea. It does neither invite to use nor to edit. :(
Sadly GitHub is the way most program are developed in a multiuser scenario.

If the goal is to maintain things, in decentralized way and to merge different modification from different people in the same file, this is the "only viable solution" to use.

It is not very user friendly at a first glance, but has enormous advantages once learned to use it, on of the many it maintain history of changes, so it is very easy to revert to e prior state if someone has done a mess.
Roy_043 wrote: Thu Jun 16, 2022 7:18 pm And there is also the proposed transition of the documentation to GitHub...
Proposed?

There is not already a GitHub repo?

Regards

Carlo D.
GitHub page: https://github.com/onekk/freecad-doc.
- In deep articles on FreeCAD.
- Learning how to model with scripting.
- Various other stuffs.

Blog: https://okkmkblog.wordpress.com/
User avatar
FBXL5
Posts: 957
Joined: Sat Aug 03, 2019 8:45 pm

Re: Wiki:Discussion usage

Post by FBXL5 »

onekk wrote: Fri Jun 17, 2022 10:58 am Sadly GitHub is the way most program are developed in a multiuser scenario.

If the goal is to maintain things, in decentralized way and to merge different modification from different people in the same file, this is the "only viable solution" to use.

It is not very user friendly at a first glance, but has enormous advantages once learned to use it, on of the many it maintain history of changes, so it is very easy to revert to e prior state if someone has done a mess.
I guess it is useful for coding, scripting, and macro editing tasks, but not for seeking information. Maybe the yet available pages are in a kind of prototype state, then I may reconsider my opinion when they are finished.

I always thought that the wiki is for the user looking for help or explanation. And I don't want a help system that I have to learn/study prior to use for advantages that I probably never need. The wiki has a history, too. So, that is no advantage for GitHub in may opinion.
User avatar
onekk
Veteran
Posts: 6098
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Wiki:Discussion usage

Post by onekk »

I guess the intention is to maintain wiki pages using GitHub, not consulting them in GitHub.

Also it is a proposal, and I see that it coulb be very handy as not everyone live in a country with mega internet speed and unlimited bandwidth that is needed to edit a page (or translate it) with a "web interface".

So having a way to download once the big bunch if data and updating only diffs will be a good solution for many

Regards.

Carlo D.
GitHub page: https://github.com/onekk/freecad-doc.
- In deep articles on FreeCAD.
- Learning how to model with scripting.
- Various other stuffs.

Blog: https://okkmkblog.wordpress.com/
User avatar
Roy_043
Veteran
Posts: 8410
Joined: Thu Dec 27, 2018 12:28 pm

Re: Wiki:Discussion usage

Post by Roy_043 »

As I understand it the GitHub documentation will replace the Wiki.
Post Reply