sod_idea.md 8.34 KB
Newer Older
1 2
Create Interactive Web Tutorials for Purr Data
----------------------------------------------
Jonathan Wilkes's avatar
Jonathan Wilkes committed
3 4 5 6

About Our Org
-------------

7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
Purr Data (started in 2014) is a visual programming language with an emphasis
on generating sound, video, 2D/3D graphics, and connecting through sensors,
input devices, and MIDI as well as OSC devices. It has an HTML5 frontend and
realtime DSP backend written in C.

Our software has an emphasis on clear documentation and user-friendliness
(hence a cat as our mascot). Our user base consists mainly of artists--
musicians, visual artists and others who run the software on consumer hardware
like laptops and tablets. Generating audio and visual in realtime on consumer
hardware is difficult enough-- Purr Data tries to streamline the process of
creating instruments, performances, and installations so that the artist does
not need to be a full-time programmer to get their work done.

For this reason, the maintainers and contributors to our project tend to have
experience as educators. They typically use the software to teach musicians
and artists how to use the computer creatively.
Jonathan Wilkes's avatar
Jonathan Wilkes committed
23

Jonathan Wilkes's avatar
Jonathan Wilkes committed
24 25
About Our Project
-----------------
Jonathan Wilkes's avatar
Jonathan Wilkes committed
26 27

### Problem
28 29 30
Purr Data is designed to be user-friendly for musicians, artists, and others
who do not have any prior programmering experience. This audience often has
has difficulty installing the software and configuring it.
Jonathan Wilkes's avatar
Jonathan Wilkes committed
31

32 33 34
It would help our new users immensely to have an online tutorial that leverages
our recent version of Purr Data that runs as a web app. This way users do not
need to install or even configure the software in order to run the tutorial,
35 36 37 38 39 40 41 42
output sound, and experiment with building their applications. Even better,
if the user runs into some problem with mis-configuring the application, they
can easily refresh the entire site and start again.

This ease of access will also allow younger users to more easily use the
software. Purr Data features a "K-12" interface geared to elementary and
high school students. Currently, however, there is no set of tutorials aimed
at a younger audience.
Jonathan Wilkes's avatar
Jonathan Wilkes committed
43 44

### Scope
45 46 47 48 49 50 51 52 53 54
We will need a technical writer and a graphic designer to put together a
compelling, approachable set of short tutorials that introduce our audience
to the core topics. There are at least three pieces of prior art that may
be used as a starting point. However, these tutorials leave many of the basic
concepts unstated (e.g., they assume the user has prior programming knowledge,
or skip over important details), aren't always written clearly, and often
feature examples that are too complicated.

The final product should be comprised of accessible prose that explains a
topic, along with a small, simple example the user can interact with leveraging
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
the web app. These tutorials should be broken into three groups:

1. A very small set of basic tutorials that focus on getting sound into the
   system (using the microphone), getting sound out of the system, and using
   a simple set of interconnected synth objects to create and manipulate the
   sound. This will serve as a set of tutorials for elementary and high-school
   students. For adult users, this will serve as a basic set of demos and
   sandbox to learn the most basic parts of the interface before diving into
   the next set of tutorials.
2. A small set of basic tutorials written for a high-school audience. These
   will be simple tutorials that explain the basic concepts of the programming
   environment, how to create and organize a program in Purr Data, and how
   to display, inspect, and output the audio data.
3. A set of basic tutorials on more general programming techniques and objects,
   as well as how they can be used in Purr Data to "glue" everything else
   together. These "glue" objects can be rather difficult for people who are
   not programmers, so it is saved for last so that the reader will have
   already spent a lot of time generating pleasing sounds before tackling it!

In short: all three tutorials will help a beginner get started as quickly as
possible with a minimum of fuss. These three sets of tutorials are not meant
to be comprehensive. The goal is to introduce the reader to the most basic
concepts of the software so that they can generate sound, create simple
programs using a simple set of tools, and learn where to find the other
resources needed to become an intermediate or advanced user.
80 81

There are a number of veteran users who can help put together simple, clear
82 83 84 85
examples for each tutorial.

The technical writer will write prose that explains the concept to a general
audience of non-programmers.
86

87 88 89
In addition to the technical writer, we'll need a graphic designer who can
create any graphs, charts, and friendly graphics featuring our Cat mascot to
help the writer elucidate a concept. Additionally,
90 91 92
since Purr Data is a diagram-based language, the designer can provide feedback
on color and design choices in the simple examples to help keep things clear
and clean looking.
Jonathan Wilkes's avatar
Jonathan Wilkes committed
93

94 95 96 97 98 99 100 101 102 103
The graphic design work will divide up like this:

1. Cat-related graphics to help make the first set of tutorials colorful and
   engaging.
2. Cat-related graphics for each new topic in the second set of tutorials,
   as well as any graphs or charts that may be helpful.
3. A few cat-related graphics in the third set of tutorials, mainly to
   add emphasis to a few sections about particularly tricky objects or
   concepts.

Jonathan Wilkes's avatar
Jonathan Wilkes committed
104
### Measuring Success
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126

*How will you know that your new documentation has helped solve your problem?
What metrics will you use, and how will you track them?*

* There is an active Facebook Group dedicated to Pd that includes a lot of
  new and aspiring users. We can use these this group to get feedback at key
  parts of the process of creating the tutorials, as well as when the final
  product is ready.
* The web app is the newest distribution of our software. Currently all
  the bug reports coming in for it are from a very small number of users--
  either developers on the project or prospective GSoC students. We will
  include a link to our issues page at the beginning and end of each set
  of tutorials to report issues or suggestions for the web app or the tutorial
  itslef. It will be very easy then to measure the increase in issues related
  to the web app and tutorial.
* There has been increasing demand on our mailing list for a "modern"
  user-friendly channel for chat. (Apparently, IRC is not popular with the
  younger devs.) For GSoC this year we will be trying out an element.io chat
  room as well as other chat solutions suggested by our younger developers.
  Once we settle on one, we will include a link at the beginning and end of
  our tutorials. Since this chat channel will be new, we can easily get a sense
  of how successful the tutorials are by the response we receive there.
Jonathan Wilkes's avatar
Jonathan Wilkes committed
127 128 129 130

Budget
------

131 132 133 134 135 136 137 138 139 140 141 142
* Technical Writer: $5000
  * tutorial writing
  * working with core devs and patch supervisor to integrate examples
    into the prose

* Graphic Artist/Animator: $1000
  * art for tutorials, including a few simple (e.g. 2-4 frame) sprites to
    brighten up the examples in the tutorials
  * advise program supervisor about readability/whitespace in the examples,
    ensure they are readable, have a sensible color palette, and other important
    visual details

143
* Program Supervisor: $250
144 145 146 147 148
  * get input from with wider community on examples for each section of the
    tutorials
  * work with graphic artist and technical writer, and revise examples to be
    clear and meaningful to the intended audience

149
* Donation for open source graphic art software: $150 (thinking Krita or Gimp
150 151 152
  here, but am open to input from the graphic artist/animator)

* T-shirts: $150
Jonathan Wilkes's avatar
Jonathan Wilkes committed
153 154 155 156

Additional Info
---------------

157 158 159 160 161 162 163 164 165 166 167
* We've participated in Google Summer of Code the past three summers.
* We have worked with a sprite artist to create a sprite sheet for our cat
  mascot. Part of that work is included in our "About Purr Data" dialog that's
  in the "Help" menu of the software. Another part was used in a demo program
  to show how to use sprite sheets from within Purr Data to create a simple
  game where the cat can interact with its own source code. These sprite
  sheets consisted of fairly involved animation of the cat walking in four
  directions, throwing numbers at visual diagrams, and getting caught in a
  web of twine. For the tutorial project proposed here, we are considering
  greatly simplified sprites of only a few frames each, which should
  substantially cut down on the expense of creating them.
Jonathan Wilkes's avatar
Jonathan Wilkes committed
168