openscad.github.com/gsod-2020.html at main · openscad/openscad.github.com · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>OpenSCAD - Google Season of Docs 2020</title>

	<link href="assets/css/style-gsod.css" rel="stylesheet">

	<link href="assets/fonts/open-sans/all.css" rel="stylesheet">
</head>
<body>


<main>

<h1><span class="green">Open</span><span class="yellow">SCAD</span> - Google Season of Docs 2020</h1>

<h2>About OpenSCAD</h2>

<img src="images/openscad.png" width="100" align="left">

<p>
    <a href="https://openscad.org/">OpenSCAD</a> is software for creating
    solid 3D CAD models. It is free software and available for Linux/UNIX,
    Windows and Mac OS X.
</p>

<p>
    OpenSCAD is not an interactive modeller. It reads a script containing a
    textual description of a 3D design and generates the model from that.
    This gives the designer full control over the modelling process and makes
    it possible to easily change any step in the modelling process or make
    designs that are defined by configurable parameters.
</p>

<p>
    OpenSCAD provides two main modelling techniques: First there is
    constructive solid geometry (aka CSG) and second there is extrusion of
    2D outlines.
</p>

<p>
    Source code is available via <a href="https://github.com/openscad/openscad">github repository</a>
    and the existing documentation can be found on Wikibooks:
    <a href="https://en.wikibooks.org/wiki/OpenSCAD_User_Manual">User Manual &amp; Language Reference</a>,
    <a href="https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/FAQ">FAQ</a>
    and <a href="https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Tips_and_Tricks">Tips & Tricks</a>
</p>

<h2>About Google Season of Docs</h2>

<img src="images/SeasonofDocs_Icon_Grey_72ppi-2019.png" width="100" align="left">
<p>
    <i>"The goal of <a href="https://developers.google.com/season-of-docs/">Season of Docs</a>
    is to provide a framework for technical writers and open source projects
    to work together towards the common goal of improving an open source
    project's documentation. For technical writers who are new to open source,
    the program provides an opportunity to gain experience in contributing to
    open source projects. For technical writers who're already working in open
    source, the program provides a potentially new way of working together.
    Season of Docs also gives open source projects an opportunity to engage
    more of the technical writing community.</i>
</p>

<p>
    All the details about how it works including guides for both Technical
    Writers and Mentors are available from the main web site. The following
    links are just some short cuts for some of the most important pages.
</p>

<ul>
    <li>Google Season of Docs <a href="https://developers.google.com/season-of-docs/docs/timeline">Timeline</a></li>
    <li><a href="https://developers.google.com/season-of-docs/docs/faq">Frequently asked questions</a> (FAQ)</li>
    <li><a href="https://developers.google.com/season-of-docs/terms/program-rules"> Season of Docs 2020 Program Rules </a></li>
</ul>

<h2>Community</h2>

<p>
    The main area where OpenSCAD is used is designing and creating models for
    3D printing. There are even complete <a href="https://github.com/Metamaquina/Metamaquina2">3D printers</a>
    or <a href="https://github.com/carlosgs/Cyclone-PCB-Factory/">CNC mills</a>
    designed in OpenSCAD, but the more common use case is for people to design
    "things" for their own use. Most notably <a href="https://www.thingiverse.com/">Thingiverse</a>,
    a site hosting and sharing a huge amount of 3D printable designs uses
    OpenSCAD as base for it's Customizer which allows people to modify the
    <a href="https://www.thingiverse.com/customizable/">parametric designs</a>
    uploaded there to fit their needs and print those.
</p>

<p>
    There are lots of other possible uses though, including math art like the
    <a href="https://mathgrrl.com/hacktastic/2018/11/the-snowflake-machine-2/">Snowflake Machine</a>
    by Laura Taalman and the <a href="http://kitwallace.co.uk/3d/knot.xq?knot-number=&selected-knot=2&components=1&crossings=&id=&action=view">Knot</a>
    and <a href="http://kitwallace.co.uk/3d/solid-index.xq?mode=full">Polyhedra</a>
    generators by Chris (Kit) Wallace. OpenSCAD helped
    <a href="https://www.poetryfoundation.org/harriet/2015/04/come-say-hello-at-awp-see-the-first-3d-printed-broadside">3D printing poetry</a>
    in both English and Braille in a tangible way, but can do
    <a href="https://twitter.com/awilkes/status/1116975681710120960">Train Tracks</a>,
    announce the <a href="https://twitter.com/caterpillar/status/1116976472013639680">new era</a>
    in Japan, design in a <a href="https://twitter.com/ferjerez3d/status/960311552627879936">single tweet</a>
    or just <a href="https://twitter.com/mikekuniavsky/status/1090651208681848838">keep things organized.</a>
</p>

<h2>Project Proposals</h2>

Overview of proposals:
<ul>
    <li><a href="#education">Create an OpenSCAD Introduction for use in Education</a></li>
    <li><a href="#tipstricks">Create an interactive Tips & Tricks Guide for OpenSCAD</a></li>
    <li><a href="#usermanual">Improve the OpenSCAD User Manual</a></li>
    <li><a href="#refmanual">Improve the OpenSCAD Language Reference Manual</a></li>
    <li><a href="#tutorial">Extend the OpenSCAD Tutorial with advanced topics</a></li>
    <li><a href="#video">Video introduction to the OpenSCAD GUI</a></li>
</ul>

We are also open for discussion about other documentation topics that could be
covered in scope of the Google Season of Docs rules.

<h3 id="education">Create an OpenSCAD Introduction for use in Education</h3>

<p>
    As can be seen in various posts on social media, OpenSCAD is already used
    in education. So far there is not much support for this, neither in form
    of specific documentation or examples included in the releases.
</p>

<p>
    Ideally the introduction would be structured in a way that it covers
    different topics in a modular way, so new modules covering other use
    cases can be added later while still maintaining the overall structure
    of the document.
</p>

<p>
    An important part of this documentation would be multiple examples showing
    each of the features taught in a module along with some suggested homework
    style questions & answers.
</p>

<p>
    Possible topics to cover, other/more suggestions welcome:
</p>
<ul>
    <li>Math Art</li>
    <li>Recursive functions</li>
    <li>Visualization of Geometry</li>
    <li>Graphical display of sequences (fibonacci)</li>
    <li>All about vectors</li>
    <li>Platonic solids</li>
    <li>Creating 3D shapes</li>
    <li>Simple animations for Physics</li>
</ul>

<table>
    <tr>
        <th>Target Audience</th>
        <td>Educators using the introduction for courses or as base for their own scripts.</td>
    </tr>
    <tr>
        <th>Scope</th>
        <td>The documentation should initially cover maybe 2 or 3 different topics and should be structured in a way to be extensible later with other topics.</td>
    </tr>
    <tr>
        <th>Current state</th>
        <td>No existing introduction yet.<br>References: OpenSCAD Projects for Junior High Teachers by Rob Ward (<a href="https://www.thingiverse.com/thing:2759515">Thingiverse 2759515</a>)</td>
    </tr>
    <tr>
        <th>Expected license</th>
        <td>CC-BY-SA or similar, code snippets must be CC0</td>
    </tr>
</table>

<h3 id="tipstricks">Create an interactive Tips & Tricks Guide for OpenSCAD</h3>

<p>
    We have a <a href="https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Tips_and_Tricks">Tips & Tricks guide</a>
    which is meant to help users with various skill level by providing
    code snippets for topics that come up multiple times. This includes
    simple coding techniques for calculating values like selectively counting
    values in a list or geometric topics like stacking different sized
    objects.
</p>

<p>
    The main idea for this project is to provide a framework for presenting
    the tips in a more interactive way using standard web techniques. This
    would either pick a number of existing tips or create some new ones based
    on research on sites like the <a href="https://forum.openscad.org/">OpenSCAD forum</a>,
    <a href="https://stackoverflow.com/tags/openscad">StackOverflow</a>,
    the <a href="https://www.reddit.com/r/openscad/">OpenSCAD subreddit</a>
    and <a href="https://www.thingiverse.com/groups/openscad/forums/general">Thingiverse Discussion Group</a>.
    Interactive in that context means to break down the more complex tips
    into smaller steps and present them to the user in a way that it's
    possible to interactively move though the steps and maybe also modify
    some of the parameters on the way.
</p>

<p>
    The resulting documentation would be expected to be similar to a screenplay
    or script showing both the content and the interaction with the user.
</p>

<table>
    <tr>
        <th>Target Audience</th>
        <td>New or novice users who are not fully confident using just the reference manual. Some basic language knowledge is assumed, so it's not expected to present very core concepts.</td>
    </tr>
    <tr>
        <th>Scope</th>
        <td>A selection of tips and tricks with medium to complex difficulty which can be broken down into multiple steps and visualized in a way that makes them easier to understand and apply to other designs.</td>
    </tr>
    <tr>
        <th>Current state</th>
        <td>No presentation exists yet, but there is a list of Tips & Tricks collected on the Wikimedia page.<br><a href="https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Tips_and_Tricks">https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Tips_and_Tricks</a></td>
    </tr>
    <tr>
        <th>Expected license</th>
        <td>CC-BY-SA or similar, code snippets must be CC0</td>
    </tr>
</table>

<h3 id="usermanual">Improve the OpenSCAD User Manual</h3>

<p>
    The OpenSCAD User Manual is maintained at Wikibooks which has the benefit
    that users can easily contribute changes but it does mean less control
    regarding what's documented and changed. The manual is usable and has
    some basic information, but is not that well structured and also skips
    over some important topics.
</p>

<p>
    It's ok to propose a new workflow / hosting for the documentation if
    there's a good argument for that which promises also long term
    maintenance.
</p>

<table>
    <tr>
        <th>Target Audience</th>
        <td>All users of the OpenSCAD (the application including the built-in editor, customizer and animation features), so the manual should cover the most important scenarios and features of the application.</td>
    </tr>
    <tr>
        <th>Scope</th>
        <td>Scope of the manual is to explain the possibilities the user interface gives (as opposed to the modelling language which is covered by the Language Manual).</td>
    </tr>
    <tr>
        <th>Current state</th>
        <td>Bits and Pieces exist but it's not well structured and is in part written with too much focus on the developer perspective<br><a href="https://en.wikibooks.org/wiki/OpenSCAD_User_Manual">https://en.wikibooks.org/wiki/OpenSCAD_User_Manual</a></td>
    </tr>
    <tr>
        <th>Expected license</th>
        <td>CC-BY-SA or similar, code snippets must be CC0</td>
    </tr>
</table>

<h3 id="refmanual">Improve the OpenSCAD Language Reference Manual</h3>

<p>
    The OpenSCAD Language Reference Manual together with the Language Cheat
    Sheet is an important resource when creating OpenSCAD designs as it
    collects information about all built-in language features and descriptions
    of the parameters available. For newer features the manual also started
    to collect the information which version of OpenSCAD is required for
    specific features. This can be very important for users that need to
    target a specific OpenSCAD version, e.g. the one used by the Thingiverse
    Customizer.
</p>

<p>
    The current version of this manual is quite usable and should cover
    almost all the functions and modules that are available. There is
    still lots of room for improvement like unifying the writing style
    and creating better images showing the result of the examples. One
    interesting option would be to automatically generate parts of the
    documentation (text structure and/or images). Alternatively a set of
    rules for generating new entries could already help a lot.
</p>

<p>
    It's ok to propose a new workflow / hosting for the documentation if
    there's a good argument for that which promises also long term
    maintenance.
</p>

<table>
    <tr>
        <th>Target Audience</th>
        <td>All users of OpenSCAD who create new or modify existing designs.</td>
    </tr>
    <tr>
        <th>Scope</th>
        <td>Scope of the manual is to explain every bulit-in language feature in detail in a clearly structured way. Ideally there should be cross references for features that can be used in multiple contexts.</td>
    </tr>
    <tr>
        <th>Current state</th>
        <td>Relatively complete and reasonably structured documentation exists, but it's lacking a single style, clear references and a good list of examples with reference pictures.<br><a href="https://en.wikibooks.org/wiki/OpenSCAD_User_Manual">https://en.wikibooks.org/wiki/OpenSCAD_User_Manual</a><br>Cheat Sheet: <a href="https://openscad.org/cheatsheet/">https://openscad.org/cheatsheet/</a> - (<a href="https://openscad.org/cheatsheet/snapshot.html">development version</a>)</td>
    </tr>
    <tr>
        <th>Expected license</th>
        <td>CC-BY-SA or similar, code snippets must be CC0</td>
    </tr>
</table>

<h3 id="tutorial">Extend the OpenSCAD Tutorial with advanced topics</h3>

<p>
    In scope of GSoD 2019 a nice introduction tutorial was created. It can be
    found at <a href="https://en.wikibooks.org/wiki/OpenSCAD_Tutorial">Wikibooks - OpenSCAD Tutorial</a>.
    This covers most of the core features and mentions some of the more
    advanced topics but goes not too much into details there.
</p>

<p>
    Some topics that could be included:
</p>

<ul>
    <li>More detailed coverage of using libraries</li>
    <li>Structure designs for easier maintenance</li>
    <li>Write reusable code and libraries</li>
    <li>Performance considerations for bigger designs</li>
    <li>Designs with multiple parts and assembly view</li>
    <li>Using the animation feature</li>
</ul>

<table>
    <tr>
        <th>Target Audience</th>
        <td>People who already have some knowledge of OpenSCAD and want to go the next step towards more complicated designs.</td>
    </tr>
    <tr>
        <th>Scope</th>
        <td>At the end of the advanced tutorial the user should have the knowledge to create and maintain complex models.</td>
    </tr>
    <tr>
        <th>Current state</th>
        <td>Introduction tutorial exists covering most core features and only touching on some more advanced topics.</td>
    </tr>
    <tr>
        <th>Expected license</th>
        <td>CC-BY-SA or similar, code snippets must be CC0</td>
    </tr>
</table>

<h3 id="video">Video introduction to the OpenSCAD GUI</h3>

<p>
    Due to the fact that OpenSCAD is script based, it does not have a very
    complicated GUI. The core GUI is basically a text editor for writing the
    code of the 2D or 3D designs. However there are a number of features that
    are not obvious but can help the user to work much more efficiently.
    In addition to special features, an overview of the common workflow of
    developing and analyzing a design would be useful.
</p>

<p>A some topics that could be covered:</p>

<ul>
    <li>Full workflow from design to export</li>
    <li>Using the different view modes</li>
    <li>Visual aids for debugging a design</li>
    <li>Changing numbers via ALT+Cursor keys</li>
    <li>Using the Customizer</li>
</ul>

<table>
    <tr>
        <th>Target Audience</th>
        <td>Depending on the topic either beginner or advanced users.</td>
    </tr>
    <tr>
        <th>Scope</th>
        <td>Short and self contained introductions of specific topics.</td>
    </tr>
    <tr>
        <th>Current state</th>
        <td>No official video documentation exists, but YouTube has lots of tutorials and stream recordings.</td>
    </tr>
    <tr>
        <th>Expected license</th>
        <td>CC-BY-SA or similar, code snippets must be CC0</td>
    </tr>
</table>

<p>
    When selecting this project, please also provide examples of previous work
    on video tutorials.
</p>

<h2>Contact</h2>

<b>Links:</b>
<ul>
    <li><b>Contact address:</b> <a href="mailto:gsod2020@openscad.org">gsod2020@openscad.org</a></li>
    <li><b>Github organization:</b> <a href="https://github.com/openscad/">https://github.com/openscad/</a> (<a href="https://github.com/openscad/openscad/">source repo</a>, <a href="https://github.com/openscad/openscad.github.com
/">web site repo</a>)</li>
    <li><b>Forum/Mailing list:</b> <a href="https://forum.openscad.org/">https://forum.openscad.org/</a></li>
</ul>

<b>People:</b>
<ul>
    <li><b><a href="https://github.com/kintel">kintel</a></b> (IRC: kintel)</li>
    <li><b><a href="https://github.com/t-paul">t-paul</a></b> (IRC: teepee)</li>
</ul>

<hr>

<small>
    Portions of this page are reproduced from work created and
    <a href="https://developers.google.com/readme/policies/">shared by Google</a>
    and used according to terms described in the <a href="https://creativecommons.org/licenses/by-nc-nd/4.0/">Creative Commons Attribution-Noncommercial-No Derivative Works 4.0 Unported License</a>
    | Logo - source: <a href="https://developers.google.com/season-of-docs/docs/press">https://developers.google.com/season-of-docs/docs/press</a>
    | Citation in Paragraph "About Google Season of Docs" - source: <a href="https://developers.google.com/season-of-docs/docs/">https://developers.google.com/season-of-docs/docs/</a>
</small>

</main>
</body>
</html>