 |
| photo by +Darren Song Ng |
Since the day I started to use Open Source software for my day to day job, I couldn't help myself looking at people that develop all this free software as if they were some kind of super programmers. They are the next step in the evolution of a programmer. I say this, because in my personal experiences, I found open source software to be of much more high quality, with regards to documentation, tests and coding practices than commercial products. Taking part in the CPAN PR Challenge, made me feel closer to them and who knows, by the end of it, I'll even start one of my own Perl module on CPAN.
Ripening the Low Hanging Fruits
I guess I'm not the only one who feels intimidated by the high quality that Perl modules exhibit with regards to software best practices and I think that's why +Neil Bowers, the guy who initiated and coordinates the whole CPAN PR challenge, put up some guidelines: lower the entry barrier to be accessible to people not involved in open source software until then.
The rules of the pull request challenge are simple, you have to make a pull request to a Perl module that's assigned to you and is on github. As Neil says, the pull request can be as large or small as you want, but the idea is that you should be contributing to the distribution in some way. This might be documentation, tests, test coverage, fixing known bugs, adding new features, or something else.
The low-hanging fruit I found is related to the documentation on github: while the vast majority of the Perl modules contain their documentation embedded in the source files in the form of POD, github shows the documentation for a module, based on the from READMEs that have to be uploaded together with the repo.
The vast majority of the Perl modules have outstanding documentation, but they don't have a README.md file in the main folder of the module, such that when a developer reaches a github repo of a perl module, he has to dig around to find out what that module does.
Small Modifications, Big Impact
So, basically, we have the documentation already available in the source files and we just have to put it in a file so that github can read it. It would be nice to have this done automatically, preferable at build time. The doc in the module is POD, we need it in markdown, in a file called README.md, because that's what github displays.
In March I got Perlbrew as a challenge. I use perlbrew heavily whenever I can - on all my dev VMs and also on production wherever that's possible, so I thought this was pretty cool.
My pull request on perlbrew is this. Although the code modifications I made are only 25 lines, the whole pull request says that there 277 lines added. That happens because the whole README.md file is generated.
I also modified some parts of the documentation to add more links into it and you can read below why I did that.
I also modified some parts of the documentation to add more links into it and you can read below why I did that.
Have look and see the aspect of the github repo of perlbrew before having a README.md file, and after having a README.md file. Don't you also think it's a much more readable and intuitive module with a proper formatted doc than without?
Positive Side Effects Created by a Good README.md
Besides the fact that it will be easier for a developer to make use of your module, you'll also get the following benefits for free:
- Search engines love content and your module will provide plenty of it to them
- Github has a high pagerank and each link from it to your online assets counts as a good backlink
- With each fork your repo gets, the backlinks to your online properties are multiplied.
- Considering how the TIOBE index is computed and the above improvements in SEO there are big chances that Perl as a whole will be better positioned from the TIOBE index point of view.
Conclusion
It feels great to be part of the cool community that Perl one is. I feel inspired by you, the developers that backs it in the way that I want to up my level and be like you guys.
The CPAN PR Challenge is just one of the ways the community does in order to encourage other people to be part of it. Thank you +Neil for starting this and for taking the time and effort to manage it.
PS: If you liked this article, share it.
0 comments:
Post a Comment