OpenSCAD - Google Season of Docs 2020

About OpenSCAD

OpenSCAD is software for creating solid 3D CAD models. It is free software and available for Linux/UNIX, Windows and Mac OS X.

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.

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

Source code is available via github repository and the existing documentation can be found on Wikibooks: User Manual & Language Reference, FAQ and Tips & Tricks

About Google Season of Docs

"The goal of Season of Docs 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.

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.

Community

The main area where OpenSCAD is used is designing and creating models for 3D printing. There are even complete 3D printers or CNC mills designed in OpenSCAD, but the more common use case is for people to design "things" for their own use. Most notably Thingiverse, 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 parametric designs uploaded there to fit their needs and print those.

There are lots of other possible uses though, including math art like the Snowflake Machine by Laura Taalman and the Knot and Polyhedra generators by Chris (Kit) Wallace. OpenSCAD helped 3D printing poetry in both English and Braille in a tangible way, but can do Train Tracks, announce the new era in Japan, design in a single tweet or just keep things organized.

Project Proposals

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

Create an OpenSCAD Introduction for use in Education

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.

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.

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.

Possible topics to cover, other/more suggestions welcome:

Target Audience Educators using the introduction for courses or as base for their own scripts.
Scope 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.
Current state No existing introduction yet.
References: OpenSCAD Projects for Junior High Teachers by Rob Ward (Thingiverse 2759515)
Expected license CC-BY-SA or similar, code snippets must be CC0

Create an interactive Tips & Tricks Guide for OpenSCAD

We have a Tips & Tricks guide 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.

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 OpenSCAD forum, StackOverflow, the OpenSCAD subreddit and Thingiverse Discussion Group. 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.

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

Target Audience 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.
Scope 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.
Current state No presentation exists yet, but there is a list of Tips & Tricks collected on the Wikimedia page.
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Tips_and_Tricks
Expected license CC-BY-SA or similar, code snippets must be CC0

Improve the OpenSCAD User Manual

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.

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.

Target Audience 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.
Scope 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).
Current state Bits and Pieces exist but it's not well structured and is in part written with too much focus on the developer perspective
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual
Expected license CC-BY-SA or similar, code snippets must be CC0

Improve the OpenSCAD Language Reference Manual

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.

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.

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.

Target Audience All users of OpenSCAD who create new or modify existing designs.
Scope 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.
Current state 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.
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual
Cheat Sheet: https://openscad.org/cheatsheet/ - (development version)
Expected license CC-BY-SA or similar, code snippets must be CC0

Extend the OpenSCAD Tutorial with advanced topics

In scope of GSoD 2019 a nice introduction tutorial was created. It can be found at Wikibooks - OpenSCAD Tutorial. This covers most of the core features and mentions some of the more advanced topics but goes not too much into details there.

Some topics that could be included:

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

Video introduction to the OpenSCAD GUI

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.

A some topics that could be covered:

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

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

Contact

Links: People:
Portions of this page are reproduced from work created and shared by Google and used according to terms described in the Creative Commons Attribution-Noncommercial-No Derivative Works 4.0 Unported License | Logo - source: https://developers.google.com/season-of-docs/docs/press | Citation in Paragraph "About Google Season of Docs" - source: https://developers.google.com/season-of-docs/docs/