[L2Ork-dev] Purr Data and Google Season of Docs

[Rukshan J. Senanayaka]

Hello,

First off, congrats on getting Purr Data selected for Google Season of Docs!

Regarding your question,

According to my personal experience in learning a new programming
language or syntax, what always never fails to help me are the in-tutorial
runnable code snippets. For example, Google Colab is such a wonderful tool.
(See https://colab.research.google.com/notebooks/intro.ipynb). You can just
read the tutorial and get the idea like reading a normal web page and run
the nearby code snippet (without leaving the tutorial) to get a better
understanding of that part of the tutorial if needed. This is applicable to
Purr Data as well i.e. keeping the patches as "runnable patch blocks" which
are a part of an HTML page that would be user-friendly for both the user
and the writer. This keeps the "writing" independent and allowing the
writer to simply insert "runnable patch blocks" where necessary will
motivate them to just "write" without worrying about technicalities like
setting up new projects, managing them, etc. The is great UX since I've
experienced this when writing blogs using WordPress myself. This would make
Purr Data documentation more flexible and dynamic since we can just update
the documentation web pages with time as needed.

Here's my input on making the tutorials themselves Purr Data patches, I
think my major concern is user experience. Let's say I'm a new user who is
willing to learn Purr Data and has no idea of it. What I'd first do is go
through the docs which include the beginner tutorials. While I'm skimming
the internet for software to get the job done, it's unlikely that I'd go to
a web app, open a tutorial patch and learn from there. I would be much
happier if there was a website with tutorials containing text and images,
where I can just click a button that says "Run Patch", and then it just
runs the part related to what I just read! Also, updating the documentation
when use patches themselves as tutorials would be a hassle, but when using
a website just for that (which includes runnable patch blocks), updating
becomes just a simple task.

Conclusion:- Using runnable patch blocks in the flow of an HTML page is
ideal for documenting Purr Data.

Final thought:- When I started to learn Python, what I first did was go to
https://www.python.org/. They have a homepage with some instructions
and a *runnable
interactive example*. I just ran it and got some idea of Python. I
immediately downloaded Python without hesitation.

Of course, these are my personal opinions and thought sharing them. I would
also love to contribute to the documentation as well.
Sorry for the long mail and your feedback and criticisms are welcome!

Regards,
Rukshan.

On Sun, Apr 18, 2021 at 12:27 AM Jonathan Wilkes <jon.w.wilkes at gmail.com>
wrote:

> Hi all,
>
> We got accepted into the Google Season of Docs program!
>
> You can see our proposed idea here:
>
>
> https://git.purrdata.net/jwilkes/summer-of-code-ideas-list/-/blob/master/sod_idea.md
>
> This is the first time we've participated, so I'm still learning how
> things will go. But if anyone has some input or would be interested in
> participating, you can respond here on the list.
>
> Initial impressions of the proposal:
>
> Just re-reading what I wrote in the sod_idea.md, one question stands out:
>
> Are the Purr Data example patches included *inside* the flow of an
> HTML page? Or, are the tutorials themselves Purr Data patches?
>
> My current opinion is the same as the one when I wrote the proposal--
> we should make it possible to load an interactive patch in a blog post
> in the same way that a library like d3 can load an interactive graph.
> Currently the web app loads from an index.html file. So we'd need to
> fix this up to load a patch in a div using a javascript method call,
> plus a hook to specify the file to be loaded.
>
> By doing it that way, the tutorial writer is free to use standard
> HTML5 tooling for links, navigation, etc.
>
> Anyway, suggestions on all of the above welcome.
>
> Best,
> Jonathan
> _______________________________________________
> L2Ork-dev mailing list
> L2Ork-dev at disis.music.vt.edu
> https://disis.music.vt.edu/listinfo/l2ork-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://disis.music.vt.edu/pipermail/l2ork-dev/attachments/20210419/89fbe68a/attachment.html>