OpenSCAD Tutorial - Google Season of Docs
It seems inappropriate to me to introduce cube() and other primitives as
functions. They get arguments and deliver some result but that is the only
common ground between them. Latter, when functions and modules will be
discussed, this will cause troubles.
A terça, 22/10/2019, 17:11, Torsten Paul via Discuss <
discuss@lists.openscad.org> escreveu:
As we are now in the middle of the GSoD timeline, here's
an update of what happened so far.
We decided that the final place for the tutorial will
be also on Wikibooks, some initial pages are places there
to register the book name, but it's not the latest state
of documentation.
(https://en.wikibooks.org/wiki/OpenSCAD_Tutorial)
For now the ongoing work can be found on our file server
as PDF files per chapter:
http://files.openscad.org/tutorial/
If you have some time to spare, please have a look and
provide feedback on what's good and/or what should be
improved. Also examples that could be used for later
chapters could be very helpful.
ciao,
Torsten.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Besides, the general approach of the text seems more like a manual than a
tutorial.
Thanks for the feedback so far, I'll try to collect answers
in this post so it will be a bit longer :-)...
First I want to highlight that I'm not the one doing
the writing, I'm only handling the organizational things
and trying to spread the word.
Thanks for all the work goes to Themistoklis who
presented the outline of the tutorial in this earlier
post:
http://forum.openscad.org/New-OpenSCAD-Member-Google-Season-of-Docs-2019-td26255.html#a26424
Also big thanks to Ryan who is helping a lot with
feedback and suggestions on the OpenSCAD IRC channel.
On 23.10.19 10:02, Robin2 wrote:
A) Who is the "Customer"
There's no clear answer to that and we don't have any
means to track who is using OpenSCAD for what (nor are
there plans to do that).
However as was said earlier, there is some kind of
"natural" focus on the 3D printing area due to a number
of reasons. 1) OpenSCAD was created to help with designing
RepRap style 3d printers 2) The Thingiverse customizer
may have introduced to quite a number of people doing
3d printing 3) OpenSCAD seems more suited to handle
smaller designs that may want to be shared and modified
in a straight forward way.
So 3D printing is probably some kind of focus area and
maybe also the main use case for explaining things in
the tutorial, I think it should be targeted at pretty
much everyone who wants to learn how to use it for
whatever reason. So far we have no official tutorial at
all, so starting out with a very specific use case seems
not useful.
On 23.10.19 10:02, Robin2 wrote:
B) Introduction chapter
Yes, I totally agree that should be added. My experience
is that this should be written last though. It still
makes sense to discuss that to shape the focus (and that
includes topic A as well).
On 23.10.19 10:02, Robin2 wrote:
C) Starting too slow (too boring?)
I think that might be part of the introduction to guide
people to a good starting point. Someone who has never
seen OpenSCAD in action before might like to see the
boring details while others may want to start at a
point where it gets more interesting (and complicated).
On 23.10.19 10:02, Robin2 wrote:
D) GUI
That's an interesting topic and I do have a number of
ideas but that's out of scope for the tutorial.
On 24.10.19 10:16, Parkinbot wrote:
E) Orthogonal view
Interesting point, I did not really notice that yet.
But what I want in the finished version is that we have
all the code in a special repo together with some
scripts to generate the images. That way we can have
all screenshots in the same style and also update easily
in case there are changes.
It's not yet filled with content, but the repo can be
found at:
https://github.com/openscad/documentation
I don't see the different views as topic of the tutorial
itself, but the introduction chapter could have some
pointers to the user manual.
On 24.10.19 16:34, Ronaldo Persiano wrote:
F) Introduce cube() and other primitives as functions
I don't understand that point. I can't find the word
"function" in any of the PDFs.
On 24.10.19 16:39, Ronaldo Persiano wrote:
G) text seems more like a manual than a tutorial
Could you elaborate on that? What would it need to be more
tutorial?
ciao,
Torsten.
Robin2 wrote
The next thing that occurred to me is how the content of the tutorial
seems
a million miles away from the discussion in many (most?) of the Threads on
this Forum - they tend to be about very esoteric problems in OpenSCAD, far
beyond the scope of a beginner. However this is not a criticism of the
Tutorial - I believe it should be aimed at beginners.
I think this is the most important topic: tutorial is aimed at beginners and
in my opinion is largely overlapped with current language manual.
What is missing, in my opinion, is a collection of "best practices" to
follow when trying to draw something more than a few cubes and cylinders.
How to start a drawing of a complex object? My first step is always where to
place origin of axis, because sometimes drawing can become quite simpler
with the right one. A best practice should show some cases and explain them.
Given a certain complex 3D shape, is it better to assemble some shapes, or
start from a big volume and remove some shapes? Obviously it depends on the
final object, and it is not unusual to find some users that build an object
with one hundred line of code, while with some smart technique can be
reduced to ten.
Moreover there is the huge topic of how to optimize designs for 3D printing,
a topic not strictly related to openscad, but that could be a strong
incentive for adopting the tool. For example, if design is targeted to 3D
printing, it is useless to achieve infinite precision, because everything
below 0.2mm is likely lost in print process, so design can be simplified and
even achieve a better final result.
--
Sent from: http://forum.openscad.org/
Em qui, 24 de out de 2019 às 17:33, Torsten Paul Torsten.Paul@gmx.de
escreveu:
On 24.10.19 16:34, Ronaldo Persiano wrote:
F) Introduce cube() and other primitives as functions
I don't understand that point. I can't find the word
"function" in any of the PDFs.
For instance, at the beginning of sphere() description we find:
Sphere[edit
https://en.wikibooks.org/w/index.php?title=OpenSCAD_Tutorial/Chapter_2&action=edit§ion=2
]
A sphere is always created centered on the origin. In complete relation to
the circle, there are 3 ways in which a sphere can be defined using
different inputs to the sphere() function.
Functions in OpenSCAD return a value and never a geometric object. Modules
never returns a value and may have children and may output a geometric
objects. sphere() is a module, not a function.
I understand that abstractly sphere() may be regarded as a function.
However, both syntactically and semantically they are different animals in
OpenSCAD.
Am Thu, 24 Oct 2019 18:32:35 +0200
schrieb Torsten Paul Torsten.Paul@gmx.de:
Thanks for all the work goes to Themistoklis who
presented the outline of the tutorial in this earlier
post:
http://forum.openscad.org/New-OpenSCAD-Member-Google-Season-of-Docs-2019-td26255.html#a26424
Also big thanks to Ryan who is helping a lot with
feedback and suggestions on the OpenSCAD IRC channel.
Sorry, my fault.
Thanks to both, Themistoklis and Ryan, for their work and dedication.
--
Mit freundlichen Grüßen
Best Regards
Peter Ragosch
On 24.10.19 18:59, bradipao wrote:
What is missing, in my opinion, is a collection of "best
practices" to follow when trying to draw something more
than a few cubes and cylinders. How to start a drawing of
a complex object?
The last sentence already make clear that it's not part
of the tutorial. "How To" is a different style of document
which is important to have, but serves a different purpose
compared to a tutorial.
See https://www.divio.com/blog/documentation/ which I
found very enlightening. The talk is great and explains
things in detail, but the main point is the 4 different
types of documents shown in chapter "The secret".
Moreover there is the huge topic of how to optimize
designs for 3D printing, a topic not strictly related to
openscad, but that could be a strong incentive for adopting
the tool. For example, if design is targeted to 3D printing,
it is useless to achieve infinite precision, because
everything below 0.2mm is likely lost in print process, so
design can be simplified and even achieve a better final
result.
That's a great point. I think there's quite a number of
cases where people complain about "OpenSCAD is unusable
slow" while sticking a $fn = 200; at the top.
I think one thing for the tutorial might be to not really
teach $fn, but always show $fa and $fs.
Special optimization topics could maybe be part of the
tutorial but I suspect the limited time frame will mean
it's not going to happen as part of this GSoD session.
It would be nice to collect ideas about this kind of
topics somewhere though. Maybe just as wiki page in one
of the github repos.
ciao,
Torsten.
On 24.10.19 19:02, Ronaldo Persiano wrote:
As the initial post already said, the intention is to host
the tutorial at Wikibooks, but the current state is the PDFs
at
http://files.openscad.org/tutorial/
ciao,
Torsten.
On 24.10.19 16:39, Ronaldo Persiano wrote:
G) text seems more like a manual than a tutorial
Could you elaborate on that? What would it need to be more
tutorial?
First, in my opinion, tutorial should not be as boring as a manual might be
by trying to explain all options of a given language element. It should be
oriented to introduce the concepts in a more hands-on approach by
building interesting examples eventually using language resources that will
be digested later. For instance, when discussing cylinders it could build a
Hanoi tower as an illustrative example using translate even before
translate have been formally introduced. The options and arguments of
primitives should ideally be introduced to simplify or enhance previous
examples. And some of them should be postponed to the point where they are
needed to construct more elaborated examples. How many times we have used
the twist argument of linear_extrude? Is that argument essential in a first
description of the operator?
On 24.10.19 19:23, Ronaldo Persiano wrote:
First, in my opinion, tutorial should not be as boring as
a manual might be by trying to explain all options of a
given language element.
Agreed. Is that looking at the old Wikibooks pages? The
current text in the PDFs is actually replacing that for
specifically this reason.
Maybe I should have not included that link in the first
place.
For instance, when discussing cylinders it could build
a Hanoi tower as an illustrative example using translate
even before translate have been formally introduced.
That's a great idea. I've added this to
https://github.com/openscad/openscad/wiki/OpenSCAD-Tutorial
which I just created trying to track the suggestions
discussed in this thread.
How many times we have used the twist argument of
linear_extrude? Is that argument essential in a first
description of the operator?
Yep, exactly I suspect it mainly belongs into
- The reference manual section for linear_extrude
- A how-to that shows how to create twisted vases
I guess there could be a much later section in the
tutorial too or something like tutorial with advanced
topics.
ciao,
Torsten.