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.
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.
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?