As you may recall from my first post, I had set some goals for myself to accomplish during the 2018 year. While it is still early into the year, I am pleased to announce that I have had two pull requests merged on GitHub!
Contribution to Ansible
The first pull request I have ever done was with Ansible. I had submitted a big report for the win_dns_client module that was putting a dent on me automating a machine build with Ansible.
The bug in question prevented the windows dns client from using DHCP to find DNS servers if I specified an empty array as noted in Ansible's documentation. I posted the bug and waited for a bit, with the only update being that the needs_triage tag was removed. Feeling that I could easily resolve this myself, I took action!
Contributions to Thruk
I will say that the first PR was pretty easy to figure out. The next two were much easier -- they were simply updates to the documentation .
We use Thruk and Naemon at my place of work. I did not set up our original environment, but have been tasked with creating an environment for a client that we will host in our colo. The requirements were that Thruk, Naemon, NagVis, and PNP4Nagios be used. Sounds easy enough.
However, when configuring cookie authentication for PNP4Nagios (and later, NagVis), I noticed that the documentation states that an option was enabled by default -- which I found that it was not.
Another user opened up an issue to address some questions about cookie authentication when using SSL. The question was a good question, that had been addressed in other issues, but had slipped through the cracks on documentation. I took the opportunity to let the maintainer develop and update the documentation for him.
The importance of it all
While the three pull requests were simple in nature and made easy fixes, they have a common theme. They provided fixes that made the documentation true. With Ansible, the documentation stated that I should be able to expect the outcome I was looking for. On the other hand, Thruk's documentation simply had some items missing.
Documentation is important for any product. If the documentation is wrong, users will find it hard to adopt your product when they expect one result but get another. On the technical side of things, if the documentation your support team utilizes is wrong, it will be harder for them to provide timely results to your customers.
You can also look at this another way. Users that have already adopted a product may find it easier to work around the problem, and may even know a fix. However, it makes it harder for new users to embrace the product -- especially in Open Source where they may not have a support contract in place.
Please note however, that the maintainers for Ansible and Thruk didn't do anything wrong -- it would be impossible to think that any products documentation is 100% accurate an up to date or that any product is bug free. In the case of open source, it should be our jobs and community members and adopters to make contributions to ensure that documentation is user-friendly and accurate.