Commit de79f197 authored by Jonathan Wilkes's avatar Jonathan Wilkes
Browse files

Update to be a documentarian-facing document

parent 7dd113c4
......@@ -4,44 +4,63 @@ Purr Data Season of Docs
Greetings Documenters!
We at Purr Data are looking forward to participating in Season of
Docs. We're currently in the process of overhauling our documentation system.
We're looking for help both testing and editing docs in the new system, as
well as doing a much needed audit of the readability and clarity of the
documentation for an audience of new users who generally have little programming
experience.
Docs. Our software has recently been updated so that it can run fully in the
browser, and we are looking to leverage that wonderous feat to create some
new tutorials to reach a broader audience with our software!
Here are the key points about our doc system:
Our aim is to create some simple, introductory web-based tutorials for an
audience of new users who generally have little programming experience. This
will be a big deal since it means new users can actually produce audio output
without having to install *anything* on their system.
* current system has some finicky restrictions on text, and it requires
the writer to manually move text around on a page to format correctly and
avoid overlapping text. Bad stuff!
* new system will allow writers to write text in a simple markdown file--
either free text, or-- preferably-- using a simple, standard template that
ensures each part of the class or feature has been covered.
We're proposing a set of three basic tutorials:
1. A small set of 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 with the mouse, or by touch. The examples will be extremely simple,
even suitable for a K-12 audience. The writing should be similarly simple,
essentially explaining to a new user (or a parent of a child) *what* to do
in order to interact with the example given.
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 a simple 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!
Challenges for documenters
--------------------------
* help us improve our documentation to better accommodate first-time users and
non-native speakers
* if you speak a second language, adding a few documentation files in your
language to show other speakers of that language how to write documentation
in our new system.
* provide fresh eyes for documentation that mostly written by insiders who
can use insider terminology that may not even be clear to veteran users
* ensure that our conversion from the old finicky inline comments to markdown
didn't introduce any errors
* provide feedback on the ergonomics of both entering a new piece of
documentation using our system, and editing existing documentation. How does
it feel to create/edit documentation in our system? Do any aspects of our
system get in the way?
* provide us feedback on how well our search functionality works to display
meaningful results in a clear and concise way.
Most (all?) of the documentation for Purr Data has been written by developers.
One of the challenges is to explain things in a way that makes sense to
non-developers. That will be one of the central challenges on this project.
The developers, maintainers, and even the general user base of the project use
a lot of "insider" lingo for features and concepts that are not familiar to
newcomers. These tutorials will elucidate *how* to use the software in a basic
sense, without relying on foreknowledge of esoteric ideas or terms.
At the same time, the content of the tutorials should be compatible with
the way current users understand the software. We don't want to misrepresent
what the software is doing, only to explain the basic concepts without
jargon or unnecessarily high-fallutin' language. :)
A Good Start
------------
* Here is Albert Graef's short tutorial for Purr Data:
https://agraef.github.io/purr-data-intro/Purr-Data-Intro.html
* Albert Graef's introductory page for Purr Data. You can see that a lot of
the document is devoted to *how* to install the software:
https://agraef.github.io/purr-data/
* The readme for the project itself: https://git.purrdata.net/jwilkes/purr-data/-/blob/master/README.md
Under Construction
------------------
We're in the process of applying to be an accepted organization this year. As
we flesh out our project proposal, we'll add more details here regarding the
specifics of our timeline, budget, and metrics.
project.
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