Documentation can make or break a product!

Dilbert.com

Never ever I have realized the importance of proper documentation until I decided to try out Shibboleth, an open source web single sin-on solution.

Shibboleth is supposedly the best open source alternative to achieve web single sign-on across applications, against more established enterprise offerings such as IBM’s Tivoli (TIM and TAM). While I do not intend to talk about the purpose of such solutions, I want to emphasize the importance of documentation for any product like this. It has been over a week that I have been trying to set-up a simple end-to-end SSO in my local environment using Shibboleth. But in the absence of proper documentation, it has turned out to be a nightmare!

Before I decided to adopt Shibboleth, I had very scary reviews about its complications. Almost everyone who had tried it mentioned that it is quite a complicated nut to crack.  Also, in spite of being the best offering, the adoption rate of Shibboleth does not sound great (at least in my knowledge).

Now, when I have gone through the entire process and close to get it running (well almost done!), I realize the root cause of the perception. The product seems good, but the documentation is horrible! It can confuse the hell out of you. In the absence of proper documentation, you are left upon your own to research through and get it up.

I am thoroughly convinced that a product/solution’s documentation is as critical as its architecture or features, UI or whatever. An OK product with a good documentation is better than a good product with bad documentation. Documentation can make or break your product!

Although I am myself not too good at it (more so out of less interest), hats off to all those people who are involved in great documentation and enabling people realize the product’s true potential.

Facebook Comments
Amit Srivastava
 

Click Here to Leave a Comment Below 0 comments

Leave a Reply:


Warning: Missing argument 2 for Jetpack_Subscriptions::comment_subscribe_init(), called in /home/koinkrun/public_html/amitsrivastava.net/wp-includes/class-wp-hook.php on line 286 and defined in /home/koinkrun/public_html/amitsrivastava.net/wp-content/plugins/jetpack/modules/subscriptions.php on line 601