[OpenSCAD] New OpenSCAD Member – Google Season of Docs 2019

Themis themistos at meng.auth.gr
Mon May 27 06:55:16 EDT 2019

First of all, congrats for the new release! I especially like the added angle
parameter in rotate_extrude() as well as the GUI customizer!

My apologies for taking quite some time to follow up my first post since
it’s the last weeks of the semester and I'm pretty busy.

I watched the presentation from PyCon Australia 2017 and I have to say that
it really puts things very nice in perspective. Very elegant presentation of
the different aspects of documentation. So just to help anyone reading this
post to get a quick context, here are the key points that are mentioned in
the video about tutorials.

Tutorials are learning oriented. They are lessons that take the reader by
the hand through a series of steps to complete a project. When writing a
tutorial, you are the teacher and you decide for the learner what they
should be doing. What matters in tutorials is learning by doing, getting
started, inspiring confidence, repeatability, immediate sense of
achievement, concreteness not abstraction, minimum necessary explanation and
no distractions.

Having these in mind I went through almost all the linked documentation from
the cheatsheet. I also went through some other random sources from the web
and through build-in examples. At this point I am confident I have a good
understanding of the capabilities of the software and the modelling approach
of constructive solid geometry in general.

Additionally, I also went back to some tutorials that I had used some years
ago, when I was a newbie with commercial CAD software, to inspect what was
the typical structure of the tutorial’s lessons that have worked for me in
the past.

So, after all this, I believe the best approach is to first present the
individual tools and technics as well as their various options independently
and then to follow up with a project that demonstrates the majority of these
tools in practice. Maybe a few additional simple examples/mini projects in
between the lessons, using tools and technics learned up to those points,
can also be pretty beneficial.

So, by mapping this approach to OpenSCAD, I believe a good approach for the
tutorial would be to:

•	Start by introducing very simple concepts, like what are the available 2D
and 3D shapes (circle(), square(), polygon(), sphere(), cube(), cylinder(),
polyhedron()) and the different options for defining them. 
•	Here it would be a good time to also mention $fa, $fs and $fn as well as
the use of variables for parametric modelling. 
•	Then to introduce the transformations (translate(), rotate(), scale()
etc.) that can be used on the primitives as well as the Boolean operators
(union(), difference(), intersection()). 
•	And now that we are playing with multiple primitives to introduce the
modifier characters. 
•	Maybe here is a good point for some simple example/mini project using the
material learned up to this point.
•	Next it would be good to explore more options for creating for creating 3D
shapes, specifically linear_extrude(), rotate_extrude(), surface(), as well
as flow control, specifically for(), intersection_for() and if(). 
•	Here it’s possibly a good point for another simple example/mini project.
•	The use of functions using some mathematical expressions (sin(), cos()
etc.) to define data for use in the design could be explored next.
•	As well as the use of modules to create reusable and modifiable parts of
•	And now that we have modules, we can also explore the use of include() and
•	Finally, its time for a project that demonstrates in practice most of the
material covered by the tutorial.

What I believe is important for the tutorial, is to try to provide a general
overview and a good coverage of the capabilities that one can easily use to
model different parts in a structured and logical way, rather than try to be
exhaustive and confuse the learner with less used or complicated technics.

Another thing to mention is that I went through the rules and requirements
in GSOD website to get the exact details regarding timeline and project
application. I believe this project can be crafted into a successful
proposal and I have relevant experience in documenting technical work and
writing short tutorial from my Master’s thesis and from a university project
that I can reference.

I would like to hear your thoughts on the proposed tutorial structure and on
any ideas about examples/projects that could be good candidates for
demonstrating in practice the covered material. We can also touch on the
presentation of the tutorial as well as on any other aspect you thing is


Sent from: http://forum.openscad.org/

More information about the Discuss mailing list