<Rant> I am an engineer by education, and have therefore studied science _a l_ot. Yet I have realised that I find it easier to read something written in , than most scientific papers written in (and I’ve never even fucking learned Spanish). Do you know why scientific research papers are so hard to read? Spanish English Because the authors of these papers these days, the “global scientific community”, consists of people whose life depends on one thing: whether they can coat their words with enough bullshit that the real scientists don’t figure out how insignificant their work really is. predominantly I’m not even alone — I know . Even Andrew Ng, one of the foremost researchers in the field of AI, himself said recently that when he first read the , he found it so hard to read that him understand what was going on. (Update 2019: was talking to the Nobel Laureate chemist Roald Hoffman at Cornell recently, and he voiced the same concerns. Go figure!) of senior scientists and experienced engineers who share this opinion plenty YOLO paper he had to ask some of his colleagues to help Now wait — to those who are offended by this claim, please allow me to expand before you write a nasty comment. You are very likely an ass-witted graduate student who thinks that writing fat tongue twisters in your paper will make you seem smart enough to hide whatever mistake it was that got you selected for your current position in the first place. (Now you can write that comment) Now, I understand that you can’t write papers simply using high-schooler vocabulary. I also acknowledge the need for the required pre-requisite knowledge while reading a scientific paper. There is indeed always a need for technical jargon, because in general the target audience of these papers are also experts in their niche fields. I’m not advocating that scientists simply replace every single “difficult sounding word”. This is about the practice of adding additional fluff to make even simple things sound more sophisticated on paper. I would argue that . So improving readability by a factor of 2x is more than enough and that’s all I ask for — . do some other a marginal increase in readability would increase a paper’s by at least 5 times readership not suggesting that you turn every paper into a textbook Read Albert Einstein’s paper if you think it can’t be done. And here’s another very influential paper written in simple language. I don’t blame you for following the herd — your entire system forces you to do that, and I have been in the same situation — my own supervisor in college once told me that my project reports should use more English and passive voice and what not, so that it “sounds like real research”. That whenever I have to choose between two words, I should use the more fancy term so that people take my work seriously. sophisticated Guess what, this culture of trying to describe in a more sophisticated way is what is in part responsible for destroying the world. And then you will get on your own faux Neil Tyson chair and complain about people who don’t understand science, deny climate change and do stupid things. Well guess what, if you tried to make science accessible to people, maybe they would actually take interest. ( ) everything Because of this tough lingo, students get put off from pursuing science and it also puts a language barrier to scientists from other countries. By crypting your knowledge you are basically hoarding it from the common people who might have taken an interest in science or research in general, which makes the whole society dumber as a result. For the record, I greatly respect Dr Tyson and his efforts to educate common people about science. But far too many “scientists” echo his sentiments while also hypocritically bloating their papers with unnecessary jargon. Allowing blind people to use elevators is one thing; but you can show real empathy and humanity by adding Braille to the elevator buttons. Documentation for programmers has reached the same unprecedented level of hyper-jargon bullshit. Sometimes I am amazed that a document which is supposed to provide can be harder to understand for a beginner than a hieroglyphic mural in the pyramid of Giza. clear and EASY instructions . This is why I’m on a quest to democratise specialized knowledge in my own way. A great challenge in reducing income inequality and saving the world is to level the playing field and educate the damn masses </Rant> My previous article, a , shocked me by attracting a non-zero audience of people who shared the same sentiment as I do. dummies’ guide to Google App Engine So today I will clean out one of the largest piles of cow-shit that new developers have to deal with. Learning how to store projects on GitHub. I have to point out that this is more of a “git” tutorial; git and are technically two different things. Moreover, git can be used for many more things than just storing your projects online. It is a ‘version control system’, and you can what that means. If you want to learn the more advanced stuff, take . GitHub waaayy Google this online course I looked at some other git tutorials online which are supposedly for beginners. But after reading and even article, I have reached the conclusion that my intelligence is sub-human, and therefore only a tutorial meant for chimpanzees and dumber would work for me. this THIS Assuming that there are other people on the planet who fall into the same category, I am writing . a GitHub tutorial for chimpanzees By the way, the I’ve found so far is this: best GitHub tutorial I highly recommend watching this if you have the time! Don’t get me wrong here— I like GitHub. But I find it hard to read the fancy documentation written by people who have forgotten the boundary between English and Java. Sorry— I digressed again. No more rants. I’ll jump right into it. By the way, PLEASE let me know if you encounter any problem following this tutorial. ZERO-BULLSHIT GITHUB GUIDE What is a repository? I keep seeing this word in every git tutorial. A repository is a fancy word to describe what is basically an online folder which stores all the code files of a particular project. So for example if you’re building an app called “Monkey species identifier”, you’ll have one big folder which has all the sub-folders and files related to that app project right? That is called a “repository” and it will have a name like “Monkey-species-identifier”. For the record, I swear this name wasn’t inspired by the title of this tutorial. The only thing that makes a ‘repository’ different from a regular folder is that it has a few hidden files which give it certain special properties. These properties allow the git system to track changes in this folder, know where it comes from, etc. With that you can even reverse and repeat changes made to the folder, and do other cool tricks, all of which fall into the big bag of “version control”. 2**. Download or install Git** There are two ways you can do this. (like I do), don’t bother surfing around the web looking for things to download. Just open your Terminal, and type “git”. The Terminal will itself tell you that you don’t have git installed, whether you’d like to install it, yada yada yada and basically take you through the process on its own. And by the end you’ll suddenly have git on your system! If you’re using a Mac If you use Windows, you’ll have to download git and then you might need something called a Powershell, which looks just like the command prompt but maybe has a different color. If you use Linux, I’m not sure what you should do, because you’re probably a geek who knows this stuff already? Why else do you even have Linux? Anyway, the official documentation for this step can be found here: https://help.github.com/articles/set-up-git/ Scroll down the mumbo-jumbo words like “forking” and “repository” etc, and go straight to the _good shit, w_here they use familiar words like “download” and “install”. 3. Once you have git, open your Terminal and do this to check if it works fine: Type ‘git’ and press enter. After this, it doesn’t matter if you have Windows/Linux/Mac etc. It’s all the same once you have installed GitHub. FIRST — Learn how to use the command line to navigate between folders. It’s actually quite simple! I don’t have time to create my own tutorial, so I’ll just refer you to this 3-minute video which explains how to use the command line very easily, in a way that a chimpanzee could understand. It’s not my own video, I found it online and it’s excellent. beautiful Click on the image link. invest 3 minutes into watching this video! Please Now, how to use GitHub? You basically need to remember only FOUR commands to get up and running: and clone, add, commit push . Creating a new project Go to github.com and sign-in. Find and click on the ‘New Repository’ button. You will see something like this in the of your window, somewhere. right-hand side 3. You will see something like this: 4. Create a repository name. There should be no spaces or punctuation in the name. For example, “My-Awesome-App”. 5. Choose the ‘Public’ option for now. To choose ‘Private’, you’ll need to upgrade your account to a paid account. It doesn’t really make a difference unless you’re working in a company and/or your code is meant to be kept secret from the world. 6. Check ‘Initialize this repository with a README’. 7. Click on ‘Create Repository’. 8. Now you’ll see this: You have created a new repository called ‘My-Awesome-App’. Currently your new Repository has only one file, which is the README.md. It was created because you chose the option to initialize the repo with a readme. :) 9. Then, go to your GitHub repo, and click on “Clone or download”. Copy the https url. 11. Now open your terminal/powershell/whatever. Navigate (using cd and ls functions) to the place where you want to set up your project folder. 12. Type “git clone” and then paste the url you copied in step #10. Press enter, as shown below: The url is the one you copied earlier. 13. You will see the folder My-Awesome-App being created. Now, add the project files (your code files) to this folder. Bingo! You have now created what is called a “local repository”, which is a clone of your repository on github.com. Now — how to store your code online and make changes to it The next step is to sync these changes with your online repository on github.com. This requires 2 steps: Tracking changes in the local repository Updating the online repository to reflect those changes For the first step, tracking changes locally, we use 2 commands, and . You don’t have to understand how exactly they work (for now). Basically it’s just the way the git system is created, so we shall roll with that. add commit 1. If your terminal is not already inside your My-Awesome-App folder, use to get inside it through the command line. cd 2. Do this: git add * This tells GitHub that you have added some new files to your project, that you want to make a part of the project. You will use the add command every time you add a new file to that folder. 17. Now, we will ‘commit’ those changes. Type the following command: For example, git commit -m “short comment”. git commit -m “Added new files” 18. Almost there! Now your local repository is up to date with the latest changes. Time to sync it with the online repository. 19. Type: git push origin master 20. By executing the above command, your terminal will upload the local files to the online repo, and now your code is stored on github! If you go to github.com now and check your repository, you will see all your code files there. It wasn’t too difficult, right? :) “What do I do next time?” The above tutorial was all about your using GitHub. But what if you make changes to that project and want to sync your updates again? Well, here’s what you do: first time Make whatever changes to your code on your computer in the local repository, and save. Command: git add * Use command . This allows you to document the change you just made to the code. You know, like telling someone “hey I added a new feature”. (If you want to record different changes to 3 different files, you will use the command thrice, by using a different comment for each file and adding at the end, like ‘ ’This way, you will be able to document the latest changes for file of code.) git commit -m “comment” FILENAME git commit -m “comment” FILENAME each Sync the changes with . git push origin master Makes sense? Now go ahead and try it out. Do let me know what you think of the tutorial. Even if it’s bad. I post all my essays on Reddit for the community to rip apart, so don’t worry I have thick skin. :) Would you like to stay in touch with me? I don’t use it as a newsletter that I can share links through, but as a two-way communication channel through which I can hear your stories and ideas. If you’re a tech company or developer, and need help in creating easy-to-understand training materials or documentation for your users, I can help you! Drop me a message on Twitter at @mngrwl
