Just read this article about the recent GitHub Open Source survey revealing that 93 percent of people reported being frustrated with “incomplete or confusing documentation”. While I definitely agree that good documentation is key to the adoption of any software, I’d like to go back in history and reflect on my rather long experience in the industry.
Thirty years ago I lived in a country called USSR. I was a young programmer back then. Iron curtain. No Google. No StackSverflow. Can you believe this? The West was far ahead in creating both hardware and software. Up until the Gorbachev’s Perestroika there was no way to officially purchase IBM or DEC computers. Skillful Soviet engineers would create copies of leading Wester brands. In the mainframe arena, the IBM System/360 and System 370 were represented by clones called “EC” (read/translate this). DEC PDP series was represented by the SM computers (see this). We knew this, but who cared?
There was an organization in Bulgaria that was translating and adapting the original IBM/DEC documentation and releasing it as official docs for the EC/SM machines. The software documentation was poorly written, but that was OK. Soviet software developers were well-educated people who could “figure it out”. I lived in Kiev, Ukraine. Since I could read English, my boss (a progressive man) would take me to a business trip to the central technical library in Moscow where we’re sitting and reading the latest issues of the Datamation magazine to learn the trends. He was skimming trough the magazines and asked me to read and translate the titles of the articles and then translate those that seemed interesting to him. These were fun business trips. We’d bring home copies of interesting articles, and most importantly, oranges, bananas, and sausages that were hard to get in Kiev.
With Perestroika, more and more of the Western software started to appear in the USSR. That was close-source software. A small number of lucky programmers (myself included) were working in the organizations that had “hard currency” and could purchase hardware and software from the West. Back then, some of the software products were sold in two versions: with or without the source code included. The latter option was a lot more expensive. Why? BECAUSE WE WOULD BE ABLE TO READ AND MODIFY THE CODE TO OUR NEEDS!
Isn’t it what the open source software is about? TO BE ABLE TO READ AND MODIFY THE CODE. The open source movement also allows and encourages you to contribute the improved software back to the community (if your employer permits).
Ironically, many of today’s enterprise programmers use the open source products not because the source code is available, but because it’s free. Day in and day out, some weird-looking geeks are stealing time from their families out for writing software for free to make the world a better place. Some other geeks spend their time on StackOverflow solving your problems for free. Millions of bloggers (myself included) write blogs happily sharing what they’ve learned about open source products.
If you like our profession, become a contributor too. You don’t have to be a superstar programmer. You may have a talent to explain the software written by others. This is a very valuable talent. Trust me, I’ve seen so many brilliant programmers who can easily write amazing code but have hard times explaining it to others.
Clone a GitHub project, find the folder with an existing documentation (or create one), write and add your article, and submit a pull request. You’ll be surprised, but most likely your contribution will be accepted and you’ll become a proud contributor to an open source project. You don’t even have to become an official contributor. Just blog about the software you like and understand. Writing about software not only helps others, but helps yourself to be better at it!