Archive for the ‘General’ Category

My experiences with writing documentation

April 12, 2011 5 comments

Like most developers I don’t like writing documentation. But when I decided to turn Solarium into an opensource project some months ago I really needed to write quite a bit of documentation, because I feel good documentation is very important for an opensource project (actually, for any project…) But there are many ways to document code. I want to share my experiences in finding a solution.

First of all I decided to make good use of phpdoc, a no-brainer. This way I can generate API docs and Phpdoc works great with IDE features like autocompletion and inline documentation.

But API docs alone are not enough, somekind of manual was needed for background info, examples, guidelines etcetera. I’ve seen or worked with multiple solutions in the past, ranging from word docs to wikis, custom websites and docbook. Some were easy to rule out (like Word docs…) but this still left me with several options with their own pros and cons. Read more…

Categories: General, Solarium

Stunnel, a practical solution for SSL/TLS

September 10, 2010 Leave a comment

TLS/SSL encryption is generaly a good thing to use, however it can in some cases be hard to implement. Stunnel is a small program that provides SSL/TLS capabilities to clients and/or servers that don’t speak SSL/TLS natively. It basically works like a proxy, transparently adding an encryption layer to the communication layer; or removing it.

There are two main use cases:

  • connecting to an encrypted service using a plaintext client
  • publish an encrypted service, while the actual backend is plaintext

There can be multiple reasons to use Stunnel instead of an implementation directly in the client or server application. You might be using an application that you cannot change. Or it might cost to much time. And Stunnel might in some cases even offer some features that are hard to achieve otherwise.

Read more…

Categories: General, PHP