One of the main reasons why it’s difficult to troubleshoot problems in complex environments is lack of documentation. This post is long overdue because it was inspired a while ago by Dan Fink’s post (again). Be sure to read it first.

From time to time, I see situations when one person leaving the company leads to a disaster that puts in danger the whole existence of multimillion businesses. Why? Because there is nobody else who knows how system works and how all its moving parts are connected. How does that happen? No knowledge sharing.

The most universal method of knowledge transfer is documenting stuff and I would argue that, most of the times, one hour of documenting brings to a business more than two hours developing new functionality in PL/SQL.

Actually, there might not even exist such know-it-all-wizard. Complex systems are not created in a matter of days or even months. Often, extreme complexity is the result of years or even decades of evolution. All those workarounds, bug fixes, re-designs, pressing deadlines — those friends of entropy win time from documentation tasks.
Continue reading ‘Avoiding Guesswork in Complex Environments’

Working mainly with App Server these days, I’ve read a manual or two… I’ve even bought them (my Oracle7 manual set takes about an arm’s worth of bookshelf and almost cost a leg too).

This all changed in 1997 when I loaded the entire database documentation set onto my new toy at the time, a Toshiba Libretto PC (which was about the same size as a hefty novel). Since then I’ve never looked back. Yes, I do periodically print out chunks of manual for reading on the train (as there’s no point keeping them longer than a few months I use all that single-sided junk mail you get), but more often than not I read documentation online. This has the following advantages:

• you can easily search for terms across several books,
• you can have several pages/books open at once in different windows,
• you’ve got the right version for the software you’re running,
• you can copy and paste any command examples you want to try.

All obvious stuff - so with such easy access to the documentation, why is it you still see lame questions (on Oracle-L, OTN discussion forums, etc) asking how to do such and such? Surely it’s quicker just to look it up… and you don’t have to wait for some kind soul to reply.

The Oracle manuals (and Cisco for that matter) are very comprehensive - yes, there are lots of them but these are complex products. Of course reading the manuals doesn’t solve a problem in itself… just not reading them means you’re more likely make things worse!