GSoC 2017 Diaries with Sugar Labs - Wrapup

User Manual for Music Blocks 

Music Blocks is a free and open source, browser based software, designed basically for students to learn music in fun and interactive way.

To get started with Music Blocks, newbies need to have a fundamental understanding of the software, what are the things that can be done and importantly how things can be done. To address these requirements, Music Blocks has two guides: 'Using Music Blocks' and 'Music Blocks Guide'. But the existing user guides lacks most of the important information about the software components, how each building blocks in the software can be related to music and especially some examples of how to create music with the software.

Project Objective:
To create a user manual which would be a comprehensive guide while providing samples and related explanations.

Project Deliverables:

In my project proposal, I defined following deliverables:

1. Improve the Music blocks user guide content to be easily understandable to newbies.
2. Implement a documentation website for Music Blocks user guide.
3. Prepare a downloadable version of Music Blocks user manual in Portable Document Format(PDF).
4. Make the website expandable for online contributions to documentation from the website itself.

At the end of the summer, I was able to achieve deliverables as follows:

1. Improve the Music blocks user guide content to be easily understandable to newbies. - Delivered, but the content has to be improved further.
2. Implement a documentation website for Music Blocks user guide. - Delivered
3. Prepare a downloadable version of Music Blocks user manual in Portable Document Format(PDF). - Delivered
4. Make the website expandable for online contributions to documentation from the website itself. - Not Delivered the originally proposed solution, but proposed another approach which is quite easy and intuitive.

The new user manual has following features as proposed initially, but the content need to be improved more.

• Hierarchical structure: Web application will be implemented in a hierarchical manner sectioning all the components and other necessary features. Done

• Using images: Components of the music block will be described using images. Done

• Using multi media: When explaining examples, apart from showing screenshots/images, videos will be also shown. In this way, a user will be able to have a better understanding about the usages/functionalities of music blocks. Done

• Downloadable project files for simple tutorials: When explaining tutorials, priority will be given to videos. Apart from that, downloadable project files will be created for those tutorials (links will be provided in relevant places). The idea is, users can download them and open them from the music block web application. In this approach, users will have hands on experience. Done

• Live demos: The idea is when the user clicks on the downloadable project link, the project file will be automatically opened on the Music Blocks website and start playing. Done

Technologies:

HTML, Bootstrap, JavaScript, PHP, MySQL

Work Summary:

According to my proposed timeline, I started working as follows:

1. Preliminary contributions and preparations

I conducted a user studies survey to identify how newbies see Music Blocks and its existing user manual.

Some valuable feedback from user studies survey which was considered while implementing my project:

• User guide should be more user friendly and should follow a user-centric design. It should be easy to search with some keywords and get the results. Components should be self descriptive, with the existing design, it's hard to get to know which component in which category.
• Putting a video tutorial at the beginning of the Home page will be an effective method to provide a user guide.
• Need to be able to enter some keywords and get results and some examples would be handy.
• Start with an example. A simple example with no explanation, but just the steps listed to give the reader a easily accomplishable task. that gives the learner motivation/incentive to go on further, now that he/she has tasted actual results using the software s/he might feel confident in moving forward.
• Use GIFs to explain things.
• It should follow a structured method where summarize each component. Also better to describe the reasons behind the categorization. Should contain examples. May be can explain the software using a scenario like in this survey. Show how to build a song using music blocks. Then go to advanced topics.
• It still doesn't answer my "how to scroll" problem. So a forum and/or faq would be nice, and the user guide can be made as an interactive web page instead of a raw pdf document.
• Include a demonstration.

After that, I worked on categorization and ordering of the content with the help of mentors.

Next step was to create mock prototypes and web templates. Here you can find some screenshots of templates I shared with mentors for discussion. A combination of Theme 1 and Theme 6 was used as user manual website.

2. Build web template

This was delivered in the given time period. 

3. Documentation

I started being delayed from here where I couldn’t complete the content within the time I suggested. I do not have a good knowledge of Music and it was quite challenging for me to complete the content and also it took a considerable amount of time in adding images to 'Components of Music Blocks' section rather than expected. Still, the content needs to be improved and I moved to next tasks on my timeline while doing this task parallelly.

4. PDF generation

I decided to do PDF generation via a PHP library as it would give more control over the process. I tried several open source PDF generators and at first implemented with the FPDF generator, but there were some issues and then chose to TCPDF generator because of its supporting functionalities specially because of converting HTML page directly into PDF preserving most of the CSS styles. It took more than as estimated for PDF generation process too.

5. Documentation guidelines

Proposed a new approach for improving the documentation and gave guidelines accordingly. Proposed a new approach for improving documentation, which utilizes functionalities available on Github. The reason for moving to this approach is since the source code of the website is open source, users can easily access it, and also when users submit changes, admins can review them before adding to the website. Since this is the exact same procedure I tried to implement, using this well-defined method is easy to use.

6. Documentation web interface

This was not delivered because of the newly proposed guidelines for improving the documentation.

7. Testing

8. Review and finalizing

Blog reports on project progress:

• GSoC 2017 Diaries with Sugar Labs - 1, May 15, 2017
• GSoC 2017 Diaries with Sugar Labs - 2, June 04, 2017
• GSoC 2017 Diaries with Sugar Labs - 3, June 25, 2017
• GSoC 2017 Diaries with Sugar Labs - 4, July 17, 2017
• GSoC 2017 Diaries with Sugar Labs - 5, July 24, 2017
• GSoC 2017 Diaries with Sugar Labs - 6, August 07, 2017

You can find links to completed work from following links:

Github repository: https://github.com/Tharangi/MusicBlocksUserManual-GSoC-2017

My commits on my repository: https://github.com/Tharangi/MusicBlocksUserManual-GSoC-2017/commits?author=Tharangi

Temporary hosted link: https://sandbox.musicblocks.net/manual-tharangi/index.php?page=welcome

Conclusion:

I would like to thank Walter Bender, and Devin Ulibarri for the immense support they gave throughout this summer to complete the project. And also extended thanks goes to Cristina De Puerto and Hrishi Patel too. Thank you very much for giving this opportunity to start my journey towards contributing to open source. It was a great experience for me to take part in Google Summer of Code 2017 with Sugar Labs!