<div dir="ltr">Hello,<div><br></div><div>First off, congrats on getting Purr Data selected for Google Season of Docs!</div><div><br></div><div>Regarding your question, </div><div><br></div><div>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 <a href="https://colab.research.google.com/notebooks/intro.ipynb">https://colab.research.google.com/notebooks/intro.ipynb</a>). 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<b> </b>"runnable patch blocks"<b> </b>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.</div><div><br></div><div>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.</div><div><br></div><div>Conclusion:- Using runnable patch blocks in the flow of an HTML page is ideal for documenting Purr Data.</div><div><br></div><div>Final thought:- When I started to learn Python, what I first did was go to <a href="https://www.python.org/">https://www.python.org/</a>. They have a homepage with some instructions and a <b>runnable interactive example</b>. I just ran it and got some idea of Python. I immediately downloaded Python without hesitation.</div><div><br></div><div>Of course, these are my personal opinions and thought sharing them. I would also love to contribute to the documentation as well.<br></div><div>Sorry for the long mail and your feedback and criticisms are welcome!<br></div><div><br></div><div>Regards,</div><div>Rukshan.</div><div></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Apr 18, 2021 at 12:27 AM Jonathan Wilkes <<a href="mailto:jon.w.wilkes@gmail.com">jon.w.wilkes@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi all,<br>
<br>
We got accepted into the Google Season of Docs program!<br>
<br>
You can see our proposed idea here:<br>
<br>
<a href="https://git.purrdata.net/jwilkes/summer-of-code-ideas-list/-/blob/master/sod_idea.md" rel="noreferrer" target="_blank">https://git.purrdata.net/jwilkes/summer-of-code-ideas-list/-/blob/master/sod_idea.md</a><br>
<br>
This is the first time we've participated, so I'm still learning how<br>
things will go. But if anyone has some input or would be interested in<br>
participating, you can respond here on the list.<br>
<br>
Initial impressions of the proposal:<br>
<br>
Just re-reading what I wrote in the sod_idea.md, one question stands out:<br>
<br>
Are the Purr Data example patches included *inside* the flow of an<br>
HTML page? Or, are the tutorials themselves Purr Data patches?<br>
<br>
My current opinion is the same as the one when I wrote the proposal--<br>
we should make it possible to load an interactive patch in a blog post<br>
in the same way that a library like d3 can load an interactive graph.<br>
Currently the web app loads from an index.html file. So we'd need to<br>
fix this up to load a patch in a div using a javascript method call,<br>
plus a hook to specify the file to be loaded.<br>
<br>
By doing it that way, the tutorial writer is free to use standard<br>
HTML5 tooling for links, navigation, etc.<br>
<br>
Anyway, suggestions on all of the above welcome.<br>
<br>
Best,<br>
Jonathan<br>
_______________________________________________<br>
L2Ork-dev mailing list<br>
<a href="mailto:L2Ork-dev@disis.music.vt.edu" target="_blank">L2Ork-dev@disis.music.vt.edu</a><br>
<a href="https://disis.music.vt.edu/listinfo/l2ork-dev" rel="noreferrer" target="_blank">https://disis.music.vt.edu/listinfo/l2ork-dev</a></blockquote></div>