Partin Pruthi

January 25, 2016

Coding requires communication skills

Making something is fun! Especially when you make something that no one has ever thought of. That doesn't happen frequently AFK. However, when we're in front of our computers, we make the impossible happen every day. We're armed with the power of microchips that can do calculations at speeds not possible even by the fastest people in the world. Our lives have become significantly easier by this. As with all things in society, all of this has been possible because of our collective effort. As the title might imply, the emphasis on that previous sentence is on 'collective'. We work together to achieve great things, because individually we are nothing. Unless we're Superman, then OK, but for the part of the world that are not DC Comic fans and don't believe in Superman, we need to work together.

Our almighty lord Satoshi has blessed us with this idea of the blockchain, distributed databases, bitcoin, which has spawned a breadth of possibilities not even thought of before. Just as Linus before him, s/he knew that the success of this idea is contingent on its openness, thus this project was open sourced from its inception. Now that we're building upon this, shouldn't we continue in the same steps? Don't we have a duty to work collectively to create stuff that makes the world a better place to live in? You may argue that we do! Of course we do, we open source everything. Provide all the source code on repositories, anyone with an internet connection can get it and use it. Yes we do, but is that good enough? Imagine Boeing building a plane, and just giving it to people. Or NASA building a space ship, putting some people in it, and just telling them to give us a call when they get to Mars. Or the worst case scenario, imagine IKEA selling its products with no manual! Yes, creating something, however wonderful, is utterly useless without any documentation on how to use it.
Documentation
Documentation is not just an explanation on how the code works. It is much more than that. The most important thing about documentation is credibility. It is easy to claim the creation of something. We have a device in our office that can actually cure cancer, the only thing about it is, we don't know how to use it. Another aspect of documentation is efficiency. Instead of wasting hours on trying to figure out how something works, shouldn't users be able to use those hours actually building something? Instead of astronauts wasting time trying to figure out how to ignite a space ship and get it to fly, shouldn't they be on their way to Mars to try and harvest potatoes? Finally, documentation provides insight on the creation of the code and the general ideas on how it works, which in turn enables users to improve it.

Another thing about documentation. Improper or incomplete documentation is just as worse as no documentation at all. Showing how something works, and in the end have the thing not work at all, ruins all credibility, wastes time, and frustrates everyone involved in the process. Imagine buying a bed at IKEA, and following directions in the manual only to end up with a three legged wobbly desk! These analogies may be somewhat extreme, but we believe they're sufficient to illustrate the raised points. One way to tackle this issue is to open source the documentation as well. Have people that figured out what works best contribute on the documentation, and enlighten others. Also, those that have the time and the will can even translate the documentation and help a whole group of people that don't have the adequate language skills.

As a plea to all developers out there, if you're writing code, and there is a distinct possibility that someone else is going to be faced with that code, please document the hell out of it. Lack of adequate documentation plagues us every day. In the development world, it's the backbone of cooperation. Explaining something as complicated as code to someone in the same room can be difficult, let alone someone a world away. Unless you're Superman. Then we can just kick back drink Mojitos and wait for you to create everything all on your own.