Release 0.4 - Telescope's Documentation Problem

Why Documentation is Important

I have been working all weekend to digest the entirety of the Telescope repository for my course. I have been mentioning it for weeks now, but I'd like to go into detail now that I know more about it. Telescope essentially grabs blog posts from a feed centralized on a Seneca College website, and displays them on a front end app. This project has been moving very quickly, it only started a month ago and we are days away from a working prototype. But as quickly as it has been moving, the documentation has not been maintained at all, something I foresaw weeks ago when I made the CONTRIBUTING.md file for the project. I intended as developers added their code they would update the documentation, but they have not. 

When setting up the environment this weekend, I had great difficulty in understanding how and why things needed to be done. This is the point of documentation, to assist people in downloading and running the environment required to start development quickly. I am devoting my time on Telescope to solving these documentation issues, not just for the current developers but future developers as well. Now to the issue.

The Issue

Basically what needed to be done was to add documentation on docker, which has become a major component of the project, and how to set the .env variables. I have to talk to several people over the next few days in order to get this information, a process I have already started. Most of the information is readily available through the commit history of the env.example file. 

Background Information and Documentation

The following paragraphs detail what I learned in finding every avenue to install docker, and get the system running in different environments:

Virtualization

I had to learn how to properly set up a virtual machine. Mainly this was to get telescope running on a system that I could use. The main issue was that docker is not readily available on Windows Home Edition. At least so I thought at first. To even run docker, you need to have a virtualization capable system, and in some cases have to enable it in the BIOS. I decided to leave this out of my documentation as it is out of the scope of the project, and there are many guides online that can help you with this process. I even linked to a few guides and youtube videos in the documentation for assistance with certain steps.

Docker

I had to learn how Docker installation works, it's requirements, and what systems it can run on. This included finding alternatives for people who did not have access to the easier methods. For example, getting Docker for macOS is as simple as downloading Docker for Desktop. It will set up docker for you and comes with docker-compose pre-installed. On the other hand, Windows 10 Pro, Education, or Enterprise are required for Docker for Desktop to work. You need to either set up a virtual machine with Ubuntu Linux, get Windows Education Edition (an option freely available from Seneca), or get Docker Toolbox, which is an older version of Docker Desktop with less features.

On top of that, I had to learn how Docker works. It didn't occur to me that Docker essentially builds a miniature virtual machine to run build instructions in a consistent environment across devices, similar to my understanding of Java and it's environment. The difference is that Docker is fully customizable, and can use Docker images to use software that you would normally have to install natively, in our case this is Redis.

Docker-Compose

Docker-compose allows you to run docker applications by starting all services with one command. It is a separate install from docker on Linux distributions, and comes with Docker for Desktop on Windows and macOS. It is vital to the project as docker-compose is required to get the docker image of Redis running as a service on the right port. 

Chocolatey

Chocolatey is a package manager that was recommended to me by my professor as an easy way to download Redis natively. Part of my job was to investigate not using docker, and I found that although you can run the website locally without any major issues, it takes a lot of configuration and extra work rather than using docker. My recommendation was to entirely remove the native set up instructions and stick to docker.

The Review Process (Pull Request)

The review process took a lot longer than I initially anticipated. It took approximately 4 days to go from pull request to merge, and there were a lot of changes along the way. I came into the process with a limited understanding of exactly how everything fit together, and I have walked out knowing exactly how it all works. I was reviewed by Manekenpix and Silvyre, who are both extremely active in the project and have done many pull requests. Some of the concerns raise were as follows:

• Code Syntax
• Wording Problems
• Grammar
• Usage of sudo (when and why)

In total, between the three of us we made 35 comments, each of which added to the discussion of how much to include, and what should be excluded. This shows it's importance, as even extremely active community members take an interest in proper documentation.

I learned many things during the review process, including:

• Docker Toolbox (Thanks to grommers00 on Github)
• Docker for Desktop on Windows Education Edition (Thanks to MeisterRed on Github)
• The proper usage of sudo
• How to properly set up docker on Linux (with post install commands)

Overall Feelings on the Project

I feel like I made a good contribution to the project. Although I didn't contribute to the code itself, I can take solace knowing that future developers that work on the project in it's next iteration will be able to adapt and understand the code faster than I could. I have already had some people thank me for my contribution, saying it helped them get their environment set up better than they had it. I have enjoyed my time in this course, and this was a nice cherry on top. But there is still one more blog post to do after this one, and it contains my proudest moment in this course.