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.

How many times it happened to you:
- Why are there forty-two underscore parameters in every new database you create?
- Because it’s our standard.
- Can I look at it?
- {proudly} Yes. It’s in every init.ora file we have!

Or another variation:

- Can I look at it?
- {proudly} Yes. Here is 42 pages document how to create new database:

Performance boosters:


and etc…

- When was this document started?
- {proudly} Oh! Forty-two years ago!
- When was it last time updated?
- Eh… I’m actually quite new here…

What are the reasons behind missing or inadequate documentation?
Just to name a few:
- It’s boring.
- We have no time for it now and it’s not a priority (it never will be) — we still missing couple reports.
- I’ll do it tomorrow.
- Project manager is not paid by number of pages of documentation produced (not that this is a good idea either).
- I’m the only one who knows this system — they must be idiots to get rid of me.
I’m sure readers can name plenty of others and please feel free to do so.

Sometimes you can avoid complexity and make systems simple by design but in real life it’s more often when you need to deal with complexity. Paraphrasing Dan — documentation will not make systems simpler but will reduce perceived complexity.

If you’ve got to support and/or develop a complex system — how do you make sure you dedicate enough time to documentation? What are the strategies to keep it up to date? How to explain the importance of documenting to the management? If you have anything to say — the comment box is at the bottom of this screen — use it. If you think that you have enough to say for the blog post — just let me know.

Find more about  , , ,

7 Responses to “Avoiding Guesswork in Complex Environments”  

  1. 1 Christian Antognini


  2. 2 Frits Hoogland

    Good points Alex! Exactly the last situation I was partly involved with.

    In my experience, setting up a successful system, either complex or simple, requires a systematic approach from the start. And, which cannot be said enough, simplicity!

    A database needs to be adjusted as little as possible. Sourcecode needs to be version controlled, Even in very small simple environments. Production environments need software releases, explicitly tagged from the version control. Not a few files to be fiddled with in order to make it work again.

    Happy easter!

  3. 3 Narendra


    Nice thoughts.
    I agree completely.
    Your last reason is very important. People, many times, do not share knowledge, due to insecurity. Sounds funny, but it is a fact. They (probably) get “married” to the company and whenever they are acknowledged as S.P.O.C. (Single Point-Of-Contact), it soothes their ego.
    Such people will do everything they can, to sabotage any plans to prepare / update documents.

  4. 4 Aleksey Tsalolikhin

    Documentation is very important and under-used in today’s IT shops.

    To help remedy that, here’s my recent post on system administrator site documentation with docbook, and a few “intro to docbook” links that were helpful to me.

  5. 5 Alex Gorbachev

    Good point. Thanks Aleksey.
    The biggest difficulty I found is to motivate engineers to write docs AND keep them up to date.

  6. 6 Graham Oakes

    Excellent points Alex.

    I would also add that writing the documentation is only useful if you ensure it’s properly distributed or can be easily found. Finding the correct location for the documentation and ensuring that it’s organised in such a way to make retrieval easy is not as simple as it could be in a large company(at least that’s what I’m observing where I work atm).

  7. 7 Alex Gorbachev

    Thanks Graham. I might be biased or just used to Oracle Database documentation style but after comparing Oracle database documentation with documentation for the products that Oracle acquired — I can only attest to your point. The ability to navigate quickly and effectively within a large documentation volumes is a must.

    But it’s not only the documents creators who should invest efforts, readers must invest enough to be familiar with organization and knowledge domain. Even when search functionality works great, you would still need to know what to search for.

    Thanks again for the feedback.

Leave a Reply

  • brother mfc 9850 driver download
  • andra download vis de iarna
  • avi uncompressed codec download
  • apostila analista tributA?rio download
  • buffy l'ammazzavampiri sesta stagione download
  • cd detonautas download gratis
  • aaja sanam madhur mp3 download
  • acrobat x pro software download
  • better keyboard apk download free
  • beastie boys download greatest hits
  • civilization colonization patch download
  • chrysler 300c manual download
  • airtel new song download video
  • cistychov mas que tu download
  • andrea costi download free mp3
  • ashawo remix mp3 download
  • auto memory manager apk download
  • autA?s jA?tAkok pc download
  • 3x10 true blood download
  • cartA?o de visita odontologia download
  • broken crescent 1 download
  • barbra streisand songbird download
  • adobe premiere download gratis cs5
  • centos 5.4 dvd iso download
  • apache poi xssf download
  • blueberry dan brown download
  • adare hithenawa damith asanka download
  • aprendendo inteligencia livro download
  • andrea bocelli mistero dell amore download
  • chaotic rpg online download
  • ap25 patch xbox 360 .exe download
  • canon ixus 980 software download
  • chico buarque discografia download free
  • cem yAlmaz divx download
  • battlefield heroes download italiano
  • bleach ost 2 download free
  • beogradski sindikat govedina download mp3
  • bhagavad gita ebook fusible download
  • besplatne melodije za mobilni download
  • buon compleanno elvis download gratis
  • capacity planning software download
  • antonia rodriguez la bamba download
  • bluetooth rfbnep driver download
  • caso 39 download dublado rmvb
  • canon mp830 software download mac
  • anya deep purple download
  • beogradski sindikat alal vera download mp3
  • blue scholar album download
  • battleship trailer 2 1080p download
  • bastille bad blood ep download free
  • caderno de exercicios medronho download
  • ampeg svx demo download mac
  • ambition tracklist wale download
  • amor a longa distancia download
  • amanhecer download baixe de tudo
  • another body murdered mp3 download
  • battleship movie download english
  • arigato ga ippai mp3 download
  • centos live cd download iso
  • adobe photoshop ch4 free download
  • carry on jatta direct download
  • android lock iphone download free
  • air sync lg download
  • champion general pype mp3 download
  • ar rahman music download
  • 1960's batman sound effects download
  • bhadra video songs download telugu
  • chiavenato administraAA?o recursos humanos download
  • chahat ali haider download
  • camp rock 2 final jam download
  • chilled dubstep & bass download
  • a*s*y*s acid glitch download
  • 40 letni prawiczek download lektor pl
  • cd nega lora download
  • chasing shadows amirah 320 download
  • cd frutos mensagem brasil download
  • 30 day trial download for office for mac
  • belkin n300 setup download
  • 20th century fox intro download wav
  • blanket on the ground download
  • brother mfl pro suite mfc 5890cn download
  • chupke se song download of saathiya
  • bartpe recovery cd download
  • ba?t cha?? Aa download idm
  • asus p5pe vm audio driver download win7
  • cinema 4d r13 download peb
  • canon mp630 treiber download
  • brokencyde album download zip
  • boney m wild planet mp3 download
  • bnf 2012 recuse free download
  • aplikacja do biegania android download
  • civ iii powerbar trainer download
  • cd pedro madeira onze download
  • aladdin magic carpet game download
  • cara download mivo tv di blackberry
  • cheek to cheek download
  • champagne showers download mp3 skull
  • b2k boys for life download
  • cartella download dock mac
  • banu navari natali mp3 download
  • ashtar command deadman's gun download mp3
  • almanaque da jovem guarda download
  • beste download ego shooter
  • bijbel voor mobiel download
  • air force one x plane download
  • call of juarez download bit
  • allods patch 1.1 download
  • as confissAes de schmidt download rmvb legendado
  • chelsea grin lifeless free download
  • assembly step by step download
  • automatically download google spreadsheet
  • a500 3.1 update download
  • animal collective rosie oh download
  • child in time download deep purple
  • 4shared download bruno mars locked out of heaven
  • activar modo download in samsung galaxy s
  • a outra metade download filme
  • business man mascot download
  • abit sg 71 audio driver download
  • calibri heading font download
  • 8i845gvm rz video driver free download
  • bisoncam treiber vista download
  • all tv chanal download
  • brother x brother vol 4 download
  • becoming the dragon download
  • 108 paras non stop download free
  • adventures of tintin 3d download
  • cinema 4d r13 download windows
  • bengal 2 game download
  • awara video songs download
  • arde outra vez remix download
  • back in time download hulk
  • cloud computing video download
  • asus m2npv vm treiber download
  • ajana kono golpo bole download mp3
  • android lock screen theme download
  • bubba shot the jukebox download
  • canon mp600 software download mac
  • adobe x windows download
  • anand utsav songs download
  • chemistry one x one download
  • bite me parker blue download traduzido
  • angry birds rovio crack download
  • a r rahman mp3 download
  • cfa l3 curriculum download
  • activex flash player patch download
  • canon photostitch download windows xp
  • book of mormon audio download free
  • antonio romero tus ojitos download mp3
  • afroman wonderful tonight download mp3
  • 138 fairy tail download
  • alas i cannot swim download free
  • aynur aydin dna mp3 download
  • automatically download pictures outlook 2011 mac
  • cisco 1130 firmware download
  • aplikacije za iphone download free
  • anthrax the big 4 download
  • arjuna sakshi malayalam movie download
  • anthony kiedis scar tissue download combine
  • bangaru konda mp3 download
  • children collide loveless video download
  • body combat tracklist download
  • business cards vector download free
  • circo de soleil download rmvb