GSoC 2016 Winds Down


Google Summer of Code 2016 has come to an end. And yes I am satisfactory to a certain level that I have produced something tangible and all of you are able to access that. 

Everything about GSoC had been awesome from the day one until the end. I feel that’s the best thing that ever happened to me, contributing to an open source project while learning tons of things regarding new technologies and best principles of coding, gathering remarkable experiences and and getting into the community, all had been very useful to me. On the other hand, I am glad that my effort had been really merged in to the production. 

During this week, I have been testing the website whether it functions properly as intended, and then documented all my work so that they would be useful for people who wish to contribute in future. 

GSoC is awesome

Everything about GSoC had been awesome from the day one until the end. I feel that’s the best thing that ever happened to me, contributing to an open source project while learning tons of things regarding new technologies and best principles of coding, gathering remarkable experiences and and getting into the community, all had been very useful to me. On the other hand, I am glad that my effort had been really merged in to the production. 

Another important thing that I find with GSoC is that I had been working and contributing to an existing project, so I had to undergo a learning phase first to understand the code base, then adhere to those coding styles, technologies and tools to get the work done. That is something challenging than developing something from scratch and that’s definitely an awesome experience when we find that our code really works. 

The other most important thing that I really feel very happy is to work under the guidance of a great mentor who has taught me lots of very useful things which are technical as well as non technical. My project would never be successful if I had done it in my own way which I am used to do everyday. His motivation let me think out of box, made me more encouraging and at the end of the day, I learned lots of interesting things. I believe that having a very generous, helpful and interactive mentor is a key factor for GSoC. The last few months had been a wonderful internship for me and I am really grateful for KDE community and Google for offering me that opportunity. 

Although it is Google SUMMER of code, being in a tropical country it's always like summer in Sri Lanka. Hence we do not get any special holidays for summer and I have gone through this competition while attending the university and doing various university assignments as well. With the limited time I have had, I am happy that I was successful in managing the time to get this project up to this state and I feel contented about it. Infact I am happy about every task that I did during my GSoC project.

What I learned

The journey up to now has not been easy because I had to learn a bunch of new technologies and have met up with a number of issues during coding and integration. 

The main thing that I learnt is doing a design oriented project using an approach that uses more design thinking. During this, I learnt lots of HCI principles related to usability. Each phase of the project had been implemented methodically so that I improved myself step by step. It had been really interesting to get the ideas and suggestions from the actual audience that use the website, which in turn taught me lots of valuable things. 

The code base had mainly used Ruby, which had been a completely new programing language for me. I learnt lots of things related to Ruby community like using Ruby gems and so on. During this project, I learnt Ruby basically and also learnt other technologies like Haml, HTML, Javascript, jQuery, CSS, Bootstrap, Nokogiri and many more. 

I also learnt about testing, which is a very important part of every project. During this project, I underwent behavioral driven development with unit testing and integration testing. I learnt how to use Rspec, Nokogiri, Capybara etc.

Then I learnt about inqlude command line client and contributed to that as well. UX is something which I love to do, with this project I learnt lots of things about front end web development as well. 

Some very important additional things that I learnt during this project are using the Inqlude workboard in Phabricator, using Git for version controlling, documenting the work, maintaining a blog, communicating with the mentor using emails, video calls etc. All these things would definitely benefit me in my future career as a software engineer. 

Work report

Repositories (Master repositories: All my work are merged to the following)

Inqlude [commits]
Inqlude-data [commits]

Documents:

Project work summary
Blog

Resources

Inqlude project on KDE's Phabricator
Workboard

Design phase

Observations
Inspiration
Storyboards
Interactive prototypes


Even though GSoC has come to a pencils down, my contributions to KDE community and Inqlude project will not halt. And here onwards I will start contributing more and more to the Inqlude project as a member of their community. With the help of my mentor Cornelius Schumacher, I was able to do a good job for the open source community. Thank you Cornelius Schumacher, KDE community and Google.



Test, validate and implement


The next phase of the project was about building a more functional prototype, which could be used for user testing and then learning. This gave some valuable input on how to improve the prototypes and where to focus when building the next step. Hence, the website had been improved bit by bit by taking the comments and suggestions from the mentor. This was kind of a peer review approach. Additionally, suggestions from the audience have also been considered to improve the layout. 

First of all, we realized that the `inqlude view` command should get an option to render with an alternative template. This can be used to implement the changes to the web site without making them to be used in production immediately. It could also be used to implement various alternatives and switch between them. Accordingly, we modified the `inqlude view` command to add a new option called `--templates` to generate the static HTML views from a directory defined by the user. With that, we could independently modify the layouts and generate the pages from different templates. Currently, we have two options for this parameter, they are `one-column` and `two-column`. Moreover, this had been validated, so that when use calls `inqlude view` with a `--templates` parameter with a non-existing directory, there should be an error message telling the user that the templates directory doesn't exist and inqlude should not try to generate the views. 

Then we started redesigning the website. I always tried to keep the new layout similar to the previous one, so that regular users would not get confused. Actually, what we really wanted was to improve the existing site by adding new features and eliminating unwanted features. It was also important to keep the site more consistent throughout all the pages. Hence all the pages of the site had been designed to stay consistent with the colors, font styles, font sizes, headings, alignments and other significant formatting of the home page. 

The task had been easy with template structure brought with Haml. Haml (HTML abstraction markup language) is based on one primary principle: that is markup should be beautiful. It’s not just beauty for beauty’s sake either. Haml accelerates and simplifies template creation as well. Thus using Haml templates had been useful for the cleanliness, readability and production speed of the website. 

Few features and functionalities of the website are implemented in JavaScript and jQuery. Some of those features are search, addition of comments etc. 

Moreover, each and every component that are used in the website have been planned in detail, then implemented and reviewed by my mentor. The functionalities have been validated properly using testing. With that, we concluded most of the project work. 



 

Prototype


In this phase, I tried implementing a prototype of the design that we finalysed. This was a very interesting task. I considered several things when designing the new layout. Some of them are using a grid layout which is also responsive, keeping the site simple and clean, using adequate amount of space, applying HCI principles related to usability etc. 

Let me show here some of the layouts that I developed. 

Home page:












Library details page:















Topics page:














  

Understanding the file structure of Inqlude


Prior the implementation of the initial prototype, it was required to have a clear understanding of the existing file structure and code of the repository. The project repository can be found here. This is written in Ruby along wih few other technologies to implement several features.The types of technologies used are,

  • Ruby for implementing the logic
  • JavaScript and CSS for font end development
  • Rspec for Behavioural Driven Development

The project repository consists of the inqlude command line client and inqlude website. The main logical implmentation can be found in scripts at `lib` directory. 

The `data` main directory contains two exmaple patches for a manifest.

The format of the JSON files for manifests are defined at `schema` directory. That contains three example manifests for `generic manifest`, `release manifest` and `proprietary release manifest`.

Rspec testing is implemented at scripts in `spec` directory. This consists of unit testing, integration testing. Some exmaple data is added to a folder called `data` inside this directory.

The `view` directory contains the scripts for the views of the inqlude website. 

Every code segment that is logically implemented at scripts in `lib` directory are tested using test cases at scripts in `spec` directory. 

There are main classes for library, manifest, manifest_handler, cli, json_object, verifier, view, settings etc. 

The inqlude command line commands are easy to use. More information about inqlude commands are found in one of my previous blog posts. 

Testing the modifications for the website can be easily viewed using static html files that are generated using `inqlude view` command.

Yet coding is fun with Ruby ..... Looking forward to lots of contributions ....


Manifest Updater

One big task of our project was to add a new categorization based on topics for libraries. By analysing the libraries, we categorized them into different topics. We came up with an initial draft for that in an Excel sheet. That can be found here.

Then we cleaned it further into a csv file. Once we are done with that, we required to update the manifests with new data. But updating metadata of 204 libraries is not an easy task which can be done manualy, beacuse there are several manifest files inside each library. So we required some mechanism to automate this process of adding topics into the libaraies.

I came up with an idea to develop a node.js tool to add topics to the manifests automatically. This tool can be found here.

The tool contains a node.js program to update the manifests with topics from the `topics.csv` file. The tool can be run by following the instructions given below.

  • Install node.js and npm.
  • Copy the library folders that contain the manifest files required to be updated and paste them at manifests directory and update_manifests directory.
  • Run npm install from this directory.
  • Then run node app.js from this directory.
  • You will find the updated manifests at update_manifests directory.

Several important things are required to be noted here.

  • You should have the `topics.csv` file in the same directory that contains `app.js`.
  • Having the manifest files at `manifests` directory is adequate, but make sure that you have the same library folder structure at both `manifests` directory and `update_manifests` directory.
  • Also make sure that you have the details for the required update activity at `topics.csv`.

Using this tool, we could easily update all the manifests with metadata about the topics that they belong to. With this, we finished another milestone of the project.




Converge


Not every idea is actionable or feasible. Only some will fit the situation and problem context. Narrowing down the design to the most viable solution happens at the third phase. That is about consolidating ideas and distilling realistic solutions. This includes taking decisions about solutions.

After all the main goal of this phase is to define a minimal viable product and decide what to test and prototype. 

Consolidating the ideas

Taking into account all of the possibilities exposed during earlier phases, we condensed the ideas that we feel the best about. For that, we carried out the following tasks. 
  • Gather a list of the most viable features based on peer reviews, analyze and criticize results
  • Identify conflicts
  • Eliminate solutions that can’t be pursued
  • Hone the list down to a minimal viable product
  • List out assumptions
  • Identify how each assumption will be tested
Some most promising ideas we found are as follows. 
  • Better search with more meaningful results.
  • Adding categories for libraries, where a library can potentially have more than one category. This probably will also include a way of filtering of the libraries based on multiple selection of topics. List of proposed categories is at https://github.com/cornelius/inqlude/tree/master/topics.
  • Highlighting new releases in a way which shows activity and gives users an indication what is active and popular.

Refining the sketches

After choosing a concrete direction, we jumped into the process of wireframing by creating some interactive prototypes that varied in interface, but offered the same basic functionalities. I used a program called Balsamiq to create interactive pdfs for the Inqlude website designs.

I made more designs and refined them further by getting them peer reviewed with my mentor. Iteration upon iteration, I adjusted the designs getting to the details while improving and refining them. These iterative designs are available here.

With that, we concluded the Converge phase of the product design sprint.


Diverge


We have successfully finished the first phase of the project, so we are now moving to the second phase. This is about creating ideas on how to address the needs of the users. It's about quantity, about thinking broad and wide, about generating a lot of input in a short time. This phase incudes iterative sketching and storyboarding.

Iterative sketching 

As this phase focuses on brainstorming and getting ideas out, we needed as much inspiration as possible by creating sketches of various possible solutions. A process of divergent thinking has been used to come up with different types of quick sketches on paper. Some of them are shown below.




More sketches are available here.

With these interative sketches, we figured out following features to be very interesting.
  • A list of latest releases gives some good content on the front page and addresses a direct users need.
  • The mouse over to show additional information such as maturity or latest release or when data was updated.
  • Some welcome text is great
  • Showing all libraries on a single page allows browser search to work across all libraries.
  • Moving the links how to get libraries, how to contribute etc. into the side bar of the web page would be great.
  • Using a symbol to indicate the platform is a powerful concept.
  • Showing the number of libraries per each category could be good information.
  • Sorting by release date could be a good way to give libraries some order and indicate activity addressing the issue of users needing to know which libraries are the good ones.
  • Should be visually appealing. Having filters styled in some nice way could be attractive. Maybe it would be nice to have labels on the list of libraries which resemble the style of the filters, so that you could visually tell, what belongs where.

Storyboarding

Using the inspiration collected from the previous phase, a set of storyboards has been created to come up with different design ideas that address the point of view. These storyboards demonstrate the work flow of what different interfaces do and how they are used to accomplish tasks in a real usage scenario. For example: work flow of somebody using the web site to find a qt library. Some of the storyboards are shown below. 





More storyboards are available here.
With that, we concluded the diverge phase of the product design sprint.