Dangerous curves

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
esr
Posts: 63
Joined: Sat Aug 21, 2021 9:10 pm
Location: Malvern, PA
Contact:

Dangerous curves

Post by esr »

I'm a very new FreeCAD user with a lot of experience writing documentation. I've been making a list of things about the FreeCAD interface that can be surprising to new users, especially those without prior CAD experience like myself.

In some of Dr. Donald Knuth's books he uses a "Dangerous curve" symbol to mark admonitions about things the reader night otherwise trip over or misconstrue. There's an SVG of it on Wikimedia at https://en.wikipedia.org/wiki/File:Knut ... symbol.svg

I've been thinking it would be good to annotate various places in the documentation with dangerous-curve admonitions for newbies, with notes designed to head off surprises. As an example, I botched the 3-D print of my first project because I forgot to force-update the body after changing a dimension in the defining sketch for the pad. Newbs like myself are likely to assume that automatic updates are triggered much more often than they actually are; a dangerous-curve admonition would be appropriate here, the only real question is where to put it.

My questions are about the mechanics.

1. Does this Wikimedia instance have a markup feature equivalent to an admonition in asciidoc, that is a hanging paragraph with an specified icon off to the left?

2. Where should I upload the dangerous-curve image to make it commonly available?
User avatar
Roy_043
Veteran
Posts: 8457
Joined: Thu Dec 27, 2018 12:28 pm

Re: Dangerous curves

Post by Roy_043 »

To my knowledge there is currently no template for this. For an overview of the most used templates see WikiPages (expand the Templates paragraph).

But before going into the practicalities of this:

Can you give a concrete example of where you would put this sign?

How often would you want to use it? I can imagine that overusing it would be annoying and also defy its purpose.

Note that in Europe we do not use this traffic sign. So maybe a different symbol should be considered?
User avatar
esr
Posts: 63
Joined: Sat Aug 21, 2021 9:10 pm
Location: Malvern, PA
Contact:

Re: Dangerous curves

Post by esr »

Roy_043 wrote: Fri Aug 27, 2021 6:44 pm To my knowledge there is currently no template for this. For an overview of the most used templates see WikiPages (expand the Templates paragraph).
I can see I would have to write one. I don't expect that to pose a huge difficulty.
Can you give a concrete example of where you would put this sign?
There's one in the post I started this thread with. It is quite surprising that any dimension change in a sketch doesn't trigger an update of any pad it's attached to, I think this must be a fossil from days of underpowered processors.

If you want another one, the fact that a sketch disappears when you pad it is surprising if one has never used a CAD program before. Without being informed otherwise a new user might interpret that disappearance as the sketch actually being deleted when it generates a 3D part.
How often would you want to use it? I can imagine that overusing it would be annoying and also defy its purpose.
I wouldn't expect to use it often myself, and would cheerfully write usage guidance discouraging overuse as I agree with your concern.

The two issues I have mentioned almost exhaust my list. The third one, if I can figure out where to put it, is that beginning constraint users often forget that you need a position constraint as well as constraints sufficient to make a sketch rigid.

I'm sure I will find another use or two as I read the wiki. But more importantly, I would like to see other documenters be reminded that new users need extra guidance and that this is something possible to write in a structured way.
Note that in Europe we do not use this traffic sign. So maybe a different symbol should be considered?
Though I knew of Knuth's dangerous-curve sign, it not the first one I found when I went looking for a dangerous-curve icon. I reviewed a couple of international-system signs with the same purpose, and I think they are sufficiently similar that the reference won't be lost on non-Americans

If you still think this is a serious issue, perhaps something could be done with the Bourbaki dangerous-curve symbol:

https://en.wikipedia.org/wiki/Bourbaki_ ... end_symbol

I note however that while I used to be a mathematician myself and recognize the Bourbaki symbol, I think the Knuth icon has wider recognition - the Bourbaki bend is almost a historical curiosity at this point.
chrisb
Veteran
Posts: 53951
Joined: Tue Mar 17, 2015 9:14 am

Re: Dangerous curves

Post by chrisb »

esr wrote: Fri Aug 27, 2021 10:09 pm If you want another one, the fact that a sketch disappears when you pad it is surprising if one has never used a CAD program before.
And that's one you should very seriously consider to remove from your list. There reasons are well explained in your other topic.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
User avatar
esr
Posts: 63
Joined: Sat Aug 21, 2021 9:10 pm
Location: Malvern, PA
Contact:

Re: Dangerous curves

Post by esr »

chrisb wrote: Fri Aug 27, 2021 10:44 pm
esr wrote: Fri Aug 27, 2021 10:09 pm If you want another one, the fact that a sketch disappears when you pad it is surprising if one has never used a CAD program before.
And that's one you should very seriously consider to remove from your list. There reasons are well explained in your other topic.
Does the fact that there are reasons for it somehow prevent it from being a surprise that newbies (especially non-CAD-experienced newbies) could use a warning about?

If so, I fail to see how.
chrisb
Veteran
Posts: 53951
Joined: Tue Mar 17, 2015 9:14 am

Re: Dangerous curves

Post by chrisb »

esr wrote: Sat Aug 28, 2021 2:00 am Does the fact that there are reasons for it somehow prevent it from being a surprise that newbies (especially non-CAD-experienced newbies) could use a warning about?
Until now you are the only one having problems with this since years. So (again) you shouldn't talk about newbiesin the plural. Using such a symbol for a single person, who should have learned by now, is overuse.

I would use it e.g. for the selection of what gets exported.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: Dangerous curves

Post by heda »

first of all, it is great if you become an actual contributor

in general I think it is a good idea to have an ability for a soft "attention" in running text, that is a common used technique in several types of documentation
it really should be a small indication, the ones that are interested in it will quickly learn to spot them even if they are very much deemphasized.


some thoughts...
  • most icons in fc are made for fc, so why not have an icon made for this?
  • is not the "info" icon more widely recognized?
  • is there any chance that you can work on the current "banner" templates, like obsolete/warning etc, they are imho too similar as it is today.
esr wrote: Fri Aug 27, 2021 10:09 pm I think this must be a fossil from days of underpowered processors.
not really, search to forum for requests to completely turn off recompute...

so the behaviour today is the adjustment to what is reasonable for "modern processors", when models/assemblies reach a certain size or complexity one really want to be in control of recomputes at user side.

with that said, here is a random thought for a mechanism that would take care of new users...

put a timer on recompute (should not be hard to do coding wise) and make a user preference for max recompute time.
then for all documents in session the setting will be to force recompute always, until that first max time is hit, when it goes to current default behaviour (if one wants to make it easy coding wise I suppose one just lets it there until the document is closed, or make it a bit more intelligent, so that if things are deleted the flag will be retested and setting adjusted).

that would quite likely take care of the majority of the "dangerous curves" for newcomers,
and it would be in line with your (in other post) principle of not doing it in documentation

at last, if there is some demarkation in running text, there should also be a category attached to it, so that new users could simply browse that category, i.e. it would be one convenient avenue to gain ability for new users to explore an overview of common pitfalls at their own behest.
User avatar
Roy_043
Veteran
Posts: 8457
Joined: Thu Dec 27, 2018 12:28 pm

Re: Dangerous curves

Post by Roy_043 »

esr wrote: Fri Aug 27, 2021 10:09 pm There's one in the post I started this thread with
I do not see a link to a forum topic.
User avatar
Roy_043
Veteran
Posts: 8457
Joined: Thu Dec 27, 2018 12:28 pm

Re: Dangerous curves

Post by Roy_043 »

chrisb wrote: Sat Aug 28, 2021 5:43 am I would use it e.g. for the selection of what gets exported.
The Std_Export page is pretty short. A user who reaches this page, reads beyond the two sentence introduction, can't miss this information. The problem is more that many users simply do not bother to read the documentation.
User avatar
esr
Posts: 63
Joined: Sat Aug 21, 2021 9:10 pm
Location: Malvern, PA
Contact:

Re: Dangerous curves

Post by esr »

chrisb wrote: Sat Aug 28, 2021 5:43 am Until now you are the only one having problems with this since years.
No. I may be the only person who has told you there's a problem here, but that's not at all the same thing.

You have to be wary of adverse-selection effects in situations like this. These effects get worse when a program has a tough learning curve, and FreeCAD's is pretty tough.

They become worse still when developers have an attitude of hostility and defensiveness towards new users who tell them about UI problems.
Post Reply