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!
User avatar
adrianinsaval
Veteran
Posts: 5534
Joined: Thu Apr 05, 2018 5:15 pm

Re: Wiki:Discussion usage

Post by adrianinsaval »

could quickly turn into a bunch of confusing, outdated or incorrect posts getting linked and stagnated there.
manos
Posts: 432
Joined: Thu Nov 12, 2020 10:48 am
Location: Greece

Re: Wiki:Discussion usage

Post by manos »

adrianinsaval wrote: Wed Jun 15, 2022 6:15 pm
It is too late now . I will comment your interesting post tommorow.
User avatar
onekk
Veteran
Posts: 6094
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Wiki:Discussion usage

Post by onekk »

Probably the "discussion page" is good as it is, probably or maybe some "code of conduct" among "wiki writers" should be present or made very visible with a link somewhere.

Or maybe adopt some politics with pages assigned to a "maintainer" and "users" could interact with the "maintainer" in some way, forum post or similar.

I know it is a big work, but If I as a user found out that a page as an error:

I write a report to the maintainer and he decide what modification have to be done to the page.

This is about some personal "bad experiences" modifying some pages and making "big mistakes" inserting "bad information" on them, so without some chaperoning I don't modify anything. :mrgreen:

Maybe if an user is willing to collaborate, he could "adopt" some pages and do the "maintainer job", for maybe some "low traffic pages" and then evolve in a more skilled "maintainer".

But this is a matter of "policy" and as a simple user, I could only suggest things, how difficult is to implement this sort of politics depends heavily on how much "skilled users" are willing to collaborate and adopt pages.

Sadly I think that the workforce is small and "skilled users" are very few people, so probably this "policy" is "too much" for the "workforce".

But without a decent documentation and some "user guides" FC 1.0 will not be a "real competitor" to commercial CADs, (If this would be one of the goals to be achieved by FC).

As usual, as a simple users I could only make noise, sadly I have not much time to spend on a "real assumption of responsability" in adopting pages, at least for now.

My two cents.

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: Wed Jun 15, 2022 6:15 pm could quickly turn into a bunch of confusing, outdated or incorrect posts.
Adrianinsaval there are plenty of "confusing, outdated or incorrect posts" at the forum. The question is of from those which has been considered as useful, problem solving or just explanatory by the users, how many are "confusing, outdated or incorrect " ?. I think very few.
It is those posts which will be referred at the discussion -or notes-tab.
Thanks
User avatar
adrianinsaval
Veteran
Posts: 5534
Joined: Thu Apr 05, 2018 5:15 pm

Re: Wiki:Discussion usage

Post by adrianinsaval »

manos wrote: Thu Jun 16, 2022 12:19 pm Adrianinsaval there are plenty of "confusing, outdated or incorrect posts" at the forum.
Exactly.
The question is of from those which has been considered as useful, problem solving or just explanatory by the users, how many are "confusing, outdated or incorrect " ?. I think very few.
It is those posts which will be referred at the discussion -or notes-tab.
Thanks
Considered useful today, outdated and confusing tomorrow
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 9:16 am ... If I as a user found out that a page as an error:
I write a report to the maintainer...
Carlo D.
Carlo D. I fully agree with you, that in order to amend a wiki page a norm must be followed. But in the mean time why not the users be informed about the issues ?
Also it is not only about errors . There are plenty of pages with ambiguous terms. What is Part ? The Workbench , an object or the container created with Std Part ? 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.
But it will help also simple users get profit of every day experience.
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.

Thanks
User avatar
onekk
Veteran
Posts: 6094
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Wiki:Discussion usage

Post by onekk »

manos wrote: Thu Jun 16, 2022 12:53 pm
Carlo D. I fully agree with you, that in order to amend a wiki page a norm must be followed. But in the mean time why not the users be informed about the issues ?
Issues on what?

If you are speaking of issues on using a command, it "has" to be integrated in the page, probably in a section with some meaninful title, like "Issues" or "Caveat".

Why complicate the page with tabs?

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"

https://wiki.freecadweb.org/Feature_edi ... ble_models

or maybe even:

https://dev.opencascade.org/doc/occt-7. ... algos.html

Or probably in some wiki page based on these post.

https://forum.freecadweb.org/viewtopic. ... 89#p500989

https://forum.freecadweb.org/viewtopic. ... 11#p463511

If these infos are not already integrated in some wiki page(s) like:

https://wiki.freecadweb.org/Part_TopoShape
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.
Same as Above, but note that, a Glossary page will be useful.

https://wiki.freecadweb.org/Basic_Attachment_Tutorial

manos wrote: Thu Jun 16, 2022 12:53 pm But it will help also simple users get profit of every day experience.
I think that reading some documentation on the Wiki, clearly indicated in a "Gettin Started" page, will be more useful.


IMHO difficulties with FreeCAD are due to two order of problems:

1) poor and fragmented Documentation especially geared toward "simple users", but many things have been recently done and will be done for 1.0 release.

2) The fact that many people came here having used another CAD (and not everytime a professional CAD) and pretend to use their abitual worflow with FC thinking that this workflow is the "most natural" if not "the unique possible" workflow.

Without speaking of the myriad of poorly made video around made only probably to raise money that use old and outdated version of FC.

Try maybe to see my effort of a scripting guide, there is some introductory chapter that are trying to explain something about FC, probably not very readable as English is not my mother language and I'm not a CAD expert, but is a try, as someone said here:
Stop complaining! Start coding!
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.

Best 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 12:49 pm Considered useful today, outdated and confusing tomorrow
Isn't the same with posts ? What is the difference ?
As far as I know I have never seen a post labelled as outdated. Why ? For many reasons:
onekk wrote: Thu Jun 16, 2022 9:16 am ...Sadly I think that the workforce is small and "skilled users" are very few people, ...
Carlo D.
Also because posts are numerous posts at the forums. But in one page about a command how many could be? . Every user who is interested could link the post at the page, to the forum.
Personally I'd like look at the notes of some commands which have tortured me every time I use them.
Maybe it will become a habit for many users to check the notes. It will not weakens forum because everything at the notes will refer to forum.
User avatar
onekk
Veteran
Posts: 6094
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Wiki:Discussion usage

Post by onekk »

manos wrote: Thu Jun 16, 2022 1:21 pm Personally I'd like look at the notes of some commands which have tortured me every time I use them.
Maybe it will become a habit for many users to check the notes. It will not weakens forum because everything at the notes will refer to forum.
But what is the matter of having a note page if all is clearly exposed in the text, in my opinion, having wrote some text, notes are only an hassle if they are too frequent and when they are grouped in some place it is difficult to link to the original places. (think of a written text with numbered notes).

If I want to specify as example the Part Loft page, where a link to a page where some meaningful text is contained:

https://wiki.freecadweb.org/Part_Loft

see:

https://wiki.freecadweb.org/Part_Loft#L ... plications

Or maybe some better "command explanation" specifying clearly steps involved.

All could be improved, but adding "another level of complexity" IMHO is not the best way to do this sort of things.

I also have had problems with FC, everyday I code for FC and everyday I have to keep a personal note that collect link to wiki pages for things my memory could not get to retain (and with ages they are increasing).

But some times ago I have learned to "write to remember" and as my handwriting is worse than my memory, I use text files (Lately Org mode Emacs Files) to organize things, and have in a "unique" place links, (links posted in my previous post were taken from this "database")

But I doubt that my personal notes could be useful to other people, as they are more "mental maps" that "meaningful text".

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
adrianinsaval
Veteran
Posts: 5534
Joined: Thu Apr 05, 2018 5:15 pm

Re: Wiki:Discussion usage

Post by adrianinsaval »

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.
Discussing changes to the wiki page is a good use of the discussions page IMO but it should not be used as "extra documentation"
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. 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. If you find pages were this is not the case better to change to that than to add some comment in the rarely visited discussion page (I at least have never visited a discussion page for a wiki I don't edit).
manos wrote: Thu Jun 16, 2022 1:21 pm Isn't the same with posts ? What is the difference ?
As far as I know I have never seen a post labelled as outdated.
Forum posts get buried and forgotten within an week given the amount of daily posts, they are not a problem and people don't expect the forum to serve as documentation, you want to add a system were forum post would be documentation, this is unmaintainable because it is not easy to edit.
Post Reply