A more pedagogical approach to Musicblocks guide/docs

[ricknjacky]

As we are upgrading musicblocks the "application" as a whole, I think it is also imperative we upgrade the documentation across the musicblocks repository.

Although the current documentation gives a descriptive overview of what individual components (blocks, widgets etc..) do and how to use them, the documentation still needs doing. I say this for two main reasons:

1) From a perspective of a user who has modicum of knowledge about concepts of music theory ( for instance me in this case), even a detailed documentation about how the widget functions or a certain block works will be a bit overwhelming and confusing at first.

• Now to tackle this I suggest we structure our guide taking inspiration from guides like react and typescript. These as we all know are JavaScript library and Superset of JavaScript respectively and the way they are organized is really great, easy to navigate, beginner friendly etc..

• Step 1 would be to host our documentation on a page separately, we already have a website for that musicblocks.net so we can just add musicblocks.net/docs/ page and host all of our current documentation with some improvements there.

• Step 2 would be to arrange the documentation in the following manner, the markdown file that we currently have is segregated astutely and I guess we don't need much doing here, just arranging the content as in the image below..
  

This way user perusing the docs always has the dropdown docs content menu to the right of their screen, making it easier to navigate through and make using/learning with Musicblocks better and more intuitive.

2) As discussed already, some gaps remain in the documentation and contents of it being a major one. As is the current version has great explanation about almost every aspect of MB, I maybe wrong here or my experience is one off, but I feel it can be enhanced in making it more "pedagogical".

• To enhance this, I suggest again taking inspiration from the two aforementioned guides, they have 2-3 sections in them for instance, react-for-beginners, react-for-designers, TS for the New Programmer and TypeScript for JS Programmers etc.
  In the same fashion, I think we can design our guide to be MB for beginners and MB generic version. MB for beginners that contains some contextual cues about concepts of Music Theory being used like a laconic description or link to that particular concept's (for eg: rhythm, solfege - what are they?) info from wiki or other akin sources.

• We can also include step-by-step guides for creating projects with MB, and also how to step by step use a particular widget.

• Project examples with a brief overview and Links to projects available on planet will be great to refer to and we can have a musicblocks.net/docs/examples for this very purpose.

@walterbender please do share your thoughts on this, thanks.

[daksh4469]

I like the idea of hosting the documentation on a separate page and arranging it in categories. It is true that even detailed documentation of widgets/blocks can be overwhelming for someone who is new to musicblocks or even the concepts of music. I would like to add a suggestion here though. We could also have small projects as examples, made just for the purpose of teaching the functionalities of various widgets and blocks. Any user would then be able to load these Sample Projects and work around them themselves to get more clarity on the platform as a whole. There already exist some examples in Planet for users to open in musicblocks but I am suggesting more widget or block-specific examples.
Appreciate your thoughts on this @ricknjacky @walterbender.

[walterbender]

We actually have a lot of examples, just not very accessible:

sugarlabs/musicblocks#2346 is in regard to the example projects
and
https://github.com/sugarlabs/musicblocks/blob/master/js/macros.js are code snippets used by the help function.

But it is hard to discover these examples. With help, you need to know about the right-click context menu, then click on the help button, then know to click on the download example button. Or you need to click through a seemingly endless set of pages in the tutorial to get what you are looking for. An overhaul for MB2.0 would be most welcome.

[daksh4469]

Yeah, exactly. We have to go under the "Examples" tab in the Global tab of Planet. Also, I believe that there are not many examples that use the widgets provided in musicblocks. Actually, I saw some examples and in them, no widgets were used at all.
We could maybe add a different tag: "Learn" or something in MB2.0 that would provide this facility.
Also, while we are at Planet, I noticed that there is a "Search for a Project" and filter by tags functionality in the Global tab but not in the Local tab. Wouldn't it be nice to have this in the Local tab too? @walterbender.

[ricknjacky]

An overhaul for MB2.0 would be most welcome.

Any heads up on plan of action?

I suggest, while we are at it (i.e. building MB2.0) we start working on the docs' overhaul in parallel. MB2.0 is still far from having same features and functionalities that MB has. We'll have to maintain and use MB as the main application for the near foreseeable future.

When it's time to move on to MB2.0 as our main application, we'd have the leverage of updating/editing the previous docs ( the ones that we're discussing about here) in the places needed. Please share your thoughts on this @walterbender.

[pikurasa]

In general, I like this idea.

We need to discuss some of the details, of course.

For some historical context, in 2017, work was done for a more-interactive manual. Please see https://sandbox.musicblocks.net/manual-tharangi/index.php

(It has not been maintained much since 2017, but the general gist is there.)

2024-04-17 Note: https://sandbox.musicblocks.net/manual-tharangi/index.php is broken at the moment as the version of PHP it used is deprecated.

I think what would help the sustainability of such a manual is if it could have deeper integration with MB. One issue of having it in a separate repo is that it will inevitably become fragmented over time.

[ricknjacky]

For some historical context, in 2017, work was done for a more-interactive manual. Please see https://sandbox.musicblocks.net/manual-tharangi/index.php

It is great, really like the way it's organized and written with all the samples and stuff. It encapsulates the idea as mentioned above, we will have to discuss the details for the same and changes. But I really like the structure of it.

I think what would help the sustainability of such a manual is if it could have deeper integration with MB.

Agreed

One issue of having it in a separate repo is that it will inevitably become fragmented over time.

I get what you are trying to convey here but, we can obviate this from happening. We can have an edit this page option that redirects users to the doc's repository. On the issue of repository stagnating or outdated over time, this happens with the current documentation that we offer as well. However, README.md then eventually gets updated over the course of time, we can practice the same here.

I'd like to hear your thoughts on this.

[ricknjacky]

[pikurasa]

One thing that may be helpful, and worth it, is an interactive tutorial within MB-v4 for first-time users.