Commit 15ca2745 authored by Jonathan Wilkes's avatar Jonathan Wilkes
Browse files

online tutorial documentation idea

parent f34b7ab4
Create Web Tutorials - Purr Data
Create Interactive Web Tutorials for Purr Data
----------------------------------------------
About Our Org
-------------
Purr Data
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.
About Your Project
------------------
### Problem
Purr Data is aimed at musicians, artists, and other people who aren't
necessarily programmers. This audience often has difficulty installing the
software and configuring it.
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.
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,
output sound, and experiment with building their applications.
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.
### Scope
We will need a technical writer and a graphic designer to put together a
......@@ -29,29 +52,117 @@ 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
the web app.
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.
There are a number of veteran users who can help put together simple, clear
examples for each tutorial. The technical writer will write prose that explains
the concept to a general audience of non-programmers.
examples for each tutorial.
The technical writer will write prose that explains the concept to a general
audience of non-programmers.
Finally, the graphic designer will work with the technical writer to produce
any graphs or charts the writer needs to elucidate a concept. Additionally,
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,
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.
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.
### Measuring Success
There is a rather active Facebook Group who we can get to test out the new
tutorial and provide feedback.
*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.
Budget
------
inline or link
* 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
* Program Supervisor: $300
* 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
* Donation for open source graphic art software: $100 (thinking Krita or Gimp
here, but am open to input from the graphic artist/animator)
* T-shirts: $150
Additional Info
---------------
* Previous experience with technical writers or documentation
* 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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment