Just a few days ago I have finally finished the PHPixie ORM library and wanted to release it immediately. I planned on writing only a small blog post outlining its basic usage, then switching to finishing off other PHPixie 3 components and only after that returning to writing detailed ORM docs. Then I remembered all the interesting projects I found on Github but have never used because they didn’t even have a README file.

There are a lot of developers that don’t care about writing tests and even more that don’t care about documentation, rather they expect users to report bugs and open issues for questions. But what really happens is their code and all their hard work is being ignored as a result.

Now, when your code is ready to ship, imagine yourself as you were writing it, think of all the sacrifices that guy has made to arrive at where you are now, remember the sleepless nights he has had and the times when he skipped on hanging out with his friends. You owe him to make his work not in vain, to make sure that when people see his library they try it out instead of moving on to the one that actually has a README file.

It is not enough to write the best code, it is as important to show how good it is. And no, a small description with 10 lines of example code is not enough, in fact it might be even worse, as it will give you some moral comfort and may prevent from writing some actual in depth documentation.

And this shouldn’t be a chore, treat is as putting icing on a cake. Even if you bake a perfect cake, if the icing looks bad nobody is going to buy it on the off chance that it might taste better. You docs should reflect all the time and effort that went into your project.