next to binaries

There are not many things you can deliver to make your customers happy: one is definitely the code, and the 2nd are the docs: user-level documentation.

I've been recently asked to review the part of the documentation for the feature we are owning, and it was a surprisingly fun thing to do. I had no different feeling when reviewing it than the one I have when cutting some clever piece of code. It felt like putting the cream on the cake. It was an easy win: improve a deliverable that the client will definitely touch, cause our customers do use the documentation.

This line probably sounds right: good software comes with good documentation. But it's the other direction I am interested in exploring right now, what can documentation do for the code?

When evaluating new software I could use, like a web framework, those that have good docs have a much higher chance of getting in my toolbox. I start by looking for a section that would give me a basic setup fast, like Up and Running in Ten Minutes. Then I am awarding additional points for an introductory video. Then I will scan for How To-s for sensitive problems and references like configuration file and API ones. I admit though that once the tool is in my inbox, a weak online help won't make me drop the tool, as long as the help is not annoying.

For software developers good documentation means marketing. You'd want to grab market share, which for freelancers especially translates into increasing the number of users of the software. My advice is Write docs and keep them up to date, ask for reviews for even better docs.

Disclaimer: this post has not been reviewed before publication, hence it might contain some typos. No excuse though if it contains stupid ideas.