Open source tabula rasa

A few days ago I’ve gave it a shot and posted a link to my project on the reddit. Amongst some positive comments, there was this one:

I would never use a library that is not documented at all

Although it was the very first version of the Sentry, a typical preview & work in progress thingy (which I did forget to mention in my post), I’ve realized that it’s high time to provide some form of documentation, otherwise why would anyone use that library, even if it was making a miracles? I thought that maybe the already existing default readme.md file with a brief decription of the project and code samples + very modest wikipage would be good enough for some time… oh boy I couldn’t be more wrong.


 

At first I’ve tried to look at my project from a distance – let’s pretend that I’m the regular user (just like you), who clearly has no idea what this library is about. I could copy the code samples from the main repository page and/or clone the repository itself that contains 2 example console applications and play with it for a while. It’s highly possible that based on this residual information I would be able to create something useful e.g. the simple monitoring application. And that’s fine, actually that’s what most of us usually do, just install the library package, jump to the code samples and start immediately working with the new tool.

However, quite often we want to do something non-standard with this tool or just find out what were the primal intentions of its author. If there’s no further documentation, well, good luck with that. So I’ve started complementing the Wiki pages, one by one. Maybe it’s not the most precise yet, but at least contains much more meaningful description of the main functionalities and most of the core interfaces and classes. That was the first step.

The next step was to add comments in code. And I’m not talking about describing e.g. some functions and why do they behave in this way instead of the another one – actually there’s no magic involved or some custom, specialized algorithm that would require a deep thinking. What I have in mind are these “enterprise-level” comments that provide a documentation for your code. Yet the most important part here is that these comments should be mostly designed for the users of your library. They are not as important to you as a single author of such library as they are for anyone else who would like to use it but doesn’t know much/sh*t about it.

Open source code comments

And trust me, it doesn’t take so much time to document your code in that way. As long as you truly know what your project is about, such kind of work may actually improve your overall code quality. I’ve fixed a few trivial bugs thanks to this, because I’ve had the chance to look at my whole project, each line of code one by one. And the final effect? Happy (or maybe just not mad) users of your tool after seeing this IntelliSense tip.

Open source code IntelliSense

And that’s usually enough – text/website documentation and IntelliSense support via comments in your code. But I’ve decided to take it a little step further, and have also provided a simple website for the project that I’m working on (using the GitHub Pages for now). Anyway, whenever you create a software (library, framework etc.) that is meant to be used by the other users who are completely new to this, always try to think about their needs. Are you sure that they will be able to deal with your tool just because you find that obvious?

5 Comments Open source tabula rasa

  1. Pingback: dotnetomaniak.pl

    1. Piotr Gankiewicz

      Actually, most of them liked the idea and there were just a few “negative” comments however, not in a way of a typical “hate” but rather a constructive criticism ;).

      Reply
  2. Chester

    Keep up the good work.

    Speaking of nice IntelliSense, I see some of your XML comments spread over multiple lines (for readability of course).

    Did you know you can use the para tag to start a newline in the IntelliSense pop-up?
    I use it often in my code, as it gives a nice break for the reader.

    Honestly I think your project is already fairly well documented, a lot more then others out there for sure. I’m a fan of your fluent interfaces for setting behaviour / configuration on the watchers btw.

    Reply
    1. Piotr Gankiewicz

      Thank you Chester, it’s really nice to hear that :). I didn’t know about the the para tag, so I’ll definitely look it up. As for the documentation, I’m looking at some mature projects to find out how it’s done properly, but on the other hand I’d like to keep the docs rather slim, instead of bloated – that’s good to know that I’m heading in the right direction ;).

      Reply

Leave a Reply to Michal Franc Cancel reply

Your email address will not be published. Required fields are marked *