OpenSCAD Tutorial - Google Season of Docs

classic Classic list List threaded Threaded
28 messages Options
12
Reply | Threaded
Open this post in threaded view
|

OpenSCAD Tutorial - Google Season of Docs

OpenSCAD mailing list
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
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

OpenSCAD mailing list
This is very interesting.

The first thing that occurred to me is a question I have posed in this Forum
before - who is the "customer?" or, "what sort of user is OpenSCAD trying to
attract?" And "what is the purpose of using OpenSCAD?" or "why would one
want to use OpenSCAD?"

I think it would actually be useful to have an introductory chapter that
sets these things out clearly because doing so will {A} give the author(s)
focus and {B} forestall comments that are unrelated to the purpose of the
tutorial and {C} give the reader the information to decide whether or not to
read the Tutorial.

I hope the aim is to attract anyone who is looking for a convenient way to
create a 3D model (most likely for 3D printing) using a program that has a
fairly easy learning curve.



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.



As far as the content is concerned, I wonder if there is rather too much of
the "follow along". I suspect it may be challenging the reader's attention
span, especially with the modern tendency to expect everything in a
sound-bite. That might be alleviated with an index and a style that allows
the reader to skip to the parts that interest him or her. However that would
require that a person could start at (say) Chapter 4 without needing to have
created his Chapter 4 starting point by working through all the stuff in the
earlier chapters. Perhaps there could be a simple way to download all the
script that would be needed at the start of Chapter 4. (By the way I just
mention Chapter 4 at random for illustration).


Finally (for now) if (as I hope) the aim is to attract users from all walks
of life and not just those with prior programming experience I believe some
effort should be put into creating an easy to use GUI front end for
OpenSCAD. I gave some details of my own attempt to do so (ClikScad) in a
recent Forum Thread. I am not claiming any greatness for my own attempt  but
I hope it may provide a basis for discussion about the idea of a GUI.

...R



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

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

OpenSCAD mailing list
Why has my Reply on this Topic appeared under some other user's name?

I strongly object to this in principle.

And from a practical point of view it means I cannot make a necessary edit
to my text.

...Robin2



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

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

MichaelAtOz
Administrator
OpenSCAD mailing list wrote

> Why has my Reply on this Topic appeared under some other user's name?
>
> I strongly object to this in principle.
>
> And from a practical point of view it means I cannot make a necessary edit
> to my text.
>
> ...Robin2
>
>
>
> --
> Sent from: http://forum.openscad.org/
>
> _______________________________________________
> OpenSCAD mailing list

> Discuss@.openscad

> http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org

Yes, apologies to all, I stuffed-up Mailman DMARC settings.
Looks like it is back to normal now.
Normal still means if you have an address from a domain with DMARC policy of
Reject* it will have difficulties. I've been trying to fix this integration
issue with Nabble.

* such as yahoo and any of their friends like aol.



-----
Admin - email* me if you need anything, or if I've done something stupid...

* click on my MichaelAtOz label, there is a link to email me.

Unless specifically shown otherwise above, my contribution is in the Public Domain; to the extent possible under law, I have waived all copyright and related or neighbouring rights to this work. Obviously inclusion of works of previous authors is not included in the above.

The TPP is no simple “trade agreement.”   Fight it! http://www.ourfairdeal.org/   time is running out!
--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Admin - email* me if you need anything, or if I've done something stupid...
* click on my MichaelAtOz label, there is a link to email me.

Unless specifically shown otherwise above, my contribution is in the Public Domain; to the extent possible under law, I have waived all copyright and related or neighbouring rights to this work.
Obviously inclusion of works of previous authors is not included in the above.
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Robin2
This post was updated on .
This is a test to see if this Post is correctly attributed to me

...Robin2

Edit to add ...

Hooray, it works.

I will now re-post my comments about the Tutorial and I would appreciate if someone could remove the earlier version.

...end of Edit



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

_______________________________________________
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Robin2
Some comments on the proposed Tutorial ...

This is very interesting.

The first thing that occurred to me is a question I have posed in this Forum
before - who is the "customer?" or, "what sort of user is OpenSCAD trying to
attract?" And "what is the purpose of using OpenSCAD?" or "why would one
want to use OpenSCAD?"

I think it would actually be useful to have an introductory chapter that
sets these things out clearly because doing so will {A} give the author(s)
focus and {B} forestall comments that are unrelated to the purpose of the
tutorial and {C} give the reader the information to decide whether or not to
read the Tutorial.

I hope the aim is to attract anyone who is looking for a convenient way to
create a 3D model (most likely for 3D printing) using a program that has a
fairly easy learning curve.



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.



As far as the content is concerned, I wonder if there is rather too much of
the "follow along". I suspect it may be challenging the reader's attention
span, especially with the modern tendency to expect everything in a
sound-bite. That might be alleviated with an index and a style that allows
the reader to skip to the parts that interest him or her. However that would
require that a person could start at (say) Chapter 4 without needing to have
created his Chapter 4 starting point by working through all the stuff in the
earlier chapters. Perhaps there could be a simple way to download all the
script that would be needed at the start of Chapter 4. (By the way I just
mention Chapter 4 at random for illustration).


Finally (for now) if (as I hope) the aim is to attract users from all walks
of life and not just those with prior programming experience I believe some
effort should be put into creating an easy to use GUI front end for
OpenSCAD. I gave some details of my own attempt to do so (ClikScad) in a
recent Forum Thread. I am not claiming any greatness for my own attempt  but
I hope it may provide a basis for discussion about the idea of a GUI.

...Robin2



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

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Peter Ragosch
In reply to this post by OpenSCAD mailing list
Am Tue, 22 Oct 2019 18:10:36 +0200
schrieb Torsten Paul via Discuss <[hidden email]>:

> For now the ongoing work can be found on our file server
> as PDF files per chapter:
>
>   http://files.openscad.org/tutorial/
>
>
> ciao,
>   Torsten.
>
>
> _______________________________________________
> OpenSCAD mailing list
> [hidden email]
> http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
>

Well done Thorsten! Keep it up!

With this tutorial, anyone who can read and write should now be able to
find their way into the scripting language of OpenSCAD.

Although I already have experience with (some commands/parts of)
OpenSCAD, I have read these chapters with great interest. For my
knowledge level, it was not necessary to work through the given
examples in detail, only the study of the source code was sufficient.
However, one explanation or the other of the given code gave me a new
and deeper insight.

As Robin2 already wrote in the first section of his email, an
Introductory chapter and a Table of Contents (as usual) certainly makes
sense.

Curious, I wait for more chapters of this tutorial and hope that in
later chapters some of the "very esoteric problems in OpenSCAD", far
beyond my knowledge, will be discussed.

--
Mit freundlichen Grüßen
Best Regards

Peter Ragosch


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

JordanBrown
In reply to this post by OpenSCAD mailing list
On 10/22/2019 1:06 PM, Robin2 via Discuss wrote:
Finally (for now) if (as I hope) the aim is to attract users from all walks
of life and not just those with prior programming experience I believe some
effort should be put into creating an easy to use GUI front end for
OpenSCAD. I gave some details of my own attempt to do so (ClikScad) in a
recent Forum Thread. I am not claiming any greatness for my own attempt  but
I hope it may provide a basis for discussion about the idea of a GUI.

Have you looked at BlocksCAD?

https://www.blockscad3d.com/editor/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Robin2
This post was updated on .
JordanBrown wrote
> Have you looked at BlocksCAD?

Yes.

Do you use Blocksad regularly? I would like to hear the experiences of people who use a GUI with OpenSCAD - but probably better in my ClikScad Thread rather than disrupting this discussion about the proposed Tutorial.

...R



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

_______________________________________________
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Parkinbot
In reply to this post by OpenSCAD mailing list
Thorsten,

the screen shots seem to use orthogonal view. Isn't that a bit
counterintuitive? If it is intended, then it might be a good idea, to
mention at least the other view. I have noticed that in the user manual both
views are used for screen shots.

Personally I use this view only in special situations, e.g. together with
axes alignment (Top, Bottom ...). Therefore I wonder if someone would use it
deliberatly in 3D model development.

- Rudolf -




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

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Ronaldo
In reply to this post by OpenSCAD mailing list
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 <[hidden email]> 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
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Ronaldo
Besides, the general approach of the text seems more like a manual than a tutorial.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

tp3
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.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

bradipao
In reply to this post by Robin2
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/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Ronaldo
In reply to this post by tp3

Em qui, 24 de out de 2019 às 17:33, Torsten Paul <[hidden email]> 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]

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.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Peter Ragosch
In reply to this post by tp3
Am Thu, 24 Oct 2019 18:32:35 +0200
schrieb Torsten Paul <[hidden email]>:

> 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


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

tp3
In reply to this post by bradipao
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.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
tp3
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

tp3
In reply to this post by Ronaldo
On 24.10.19 19:02, Ronaldo Persiano wrote:
> https://en.wikibooks.org/w/index.php?title=OpenSCAD_Tutorial/Chapter_2

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.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

Ronaldo
In reply to this post by tp3



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?

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: OpenSCAD Tutorial - Google Season of Docs

tp3
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.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
12