Open-Source Software Could Have Great Documentation

During one of my Network Automation workshops one of the attendees said: “Why are you using open-source software? It’s so poorly documented and impossible to set up.”

I totally understood what he was trying to say (I’ve seen too many examples of just read the code approach), but fortunately there are still people who understand the value of documentation.

For starters, Jinja2 and Ansible (the tools I use during hands-on parts of the workshop) have pretty good documentation, and sometimes you get totally surprised by what you see on GitHub. I’ll give you just two recent examples:

So it is possible to have well-documented open-source software assuming the author(s) of the software actually care about their users (and no, I will not start another rant about people spending time on glitzy demos instead of writing usable documentation).

Finally, for some choice comments on other less-documented parts of open source landscape, enjoy this talk by Artur Bergman.

5 comments:

  1. David Barroso 13 April 2016 11:20
    /rant on

    As the maintainer of two open source projects related to the network I tend to disagree a bit with the statement `It’s so poorly documented and impossible to set up` and agree more towards Artur Bergman's statements on that video.

    What I realized is that when most people complain about 'lack of documentation' what they really mean is 'I couldn't find a blogpost or a stackoverflow question solving my very same exact problem'. If you really want to learn, start with the basics, try things out and ASK. A-S-K. Documentation might suck but the community is full of super friendly people willing to help and that would be extremely happy to help you and even reviewing a PR with some enhancements to the documentation by someone that just learnt something about the project. Maybe the maintainer overlooked something because he/she thought it was too obvious but it wasn't : )

    In summary, in most of cases "It’s so poorly documented and impossible to set up" equals to "I am lazy to solve the problem myself, I couldn't find a blog post with a recipe to solve it and I am too lazy to even join a mailing list, IRC or slack and ask". Maybe not on that particular case but most of the times ;)

    /rant off
    Replies
    1. Unknown 13 April 2016 17:32
      It's not laziness to solve the Problem. Most likely Lack of time to dig too deep. Documentation can prevent you to answer again and again the same question. Users might not be interested in the insights. They like to use your tools/gadget/app or what ever it is. So from my point of view level of documentation depends on who you like to address
    2. Ivan Pepelnjak 13 April 2016 19:49
      Hi David,

      I totally understand your point (you wouldn't believe how many LMGTFY questions I get - particularly annoying if the answer is a link to my blog post), but unfortunately I've seen open source projects where I had no idea whatsoever how to get started (apart from "this is how you install it") after reading all publicly available documentation.
  2. Anonymous 13 April 2016 14:52
    From the other side of the coin, operational networks and systems must be well understood. This is why good documentation is so important for commercial adoption. To go beyond pet project, software must become a known and trusted solution. Businesses tend to choose slow, reliable, and well understood solutions over slick solutions that nobody operates or understands. It depends on the individual business and appetite for risk, but that is true as a general rule.
  3. Salman Naqvi 13 April 2016 15:08
    I've had the same struggles with even with very well documented and well deployed solutions (e.g. Request Tracker, PHPmyFAQ, Observium, Zenoss Core). I LOVE Open Source software for MANY different reasons, but, I consistently hit very hard walls with network centric colleagues and management who don't want the additional troubles associated with Open Source products. They want something that they can install and setup reasonably easily and can CALL somebody when something goes wrong - instead of relying on forums, no matter how good they may be.

    I really wish more Open Source projects natively offered PAID support (instead of getting it through third parties, which has it's own weaknesses). Luckily, the examples I mentioned above do offer paid support to varying degrees. They may be good examples to follow for others in the OSS community, especially those working on networking related OSS initiatives.
Add comment
Home
Sidebar