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:
_db_aging_touch_time=…
_db_aging_stay_count=…
_db_writer_chunk_writes=…
_discrete_transactions_enabled=…

Bugs:
_kgl_latch_count=…
_kgl_bucket_count=…
_lm_rcfg_timeout=…

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

    Amen!

  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

    Alex,

    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


  • dresss girl to please wife
  • mature ebony lesbian
  • grannys wide open pussy
  • free young buing breast pics
  • tessa taylor facial fest torrent
  • clitoral orgasm movies
  • naked mile eastern girl
  • free huge tits lesbian videos
  • pussy big clitoris
  • free big tits sex videos
  • anime young
  • all free anal movies
  • xvideos pussy eating
  • hot naked chicks pics free
  • big titty white girl free
  • fuck slave girl tv
  • threesome mom and sex
  • board beauty little girls
  • naked of girls
  • faq asian massage parlor anal
  • big boobed hot mature xxx
  • young and fresh pussy
  • winnona ryder topless pictures
  • American pie naked mile sex
  • Big tits in car
  • young teenagers sex galleries
  • beauty stereotypes affect on teens
  • women school girl sex costumes
  • tube lesbi videos savanah samson
  • Girl fucking great dane
  • girls fuck each other
  • free redhaired teenage girls nude
  • hardcore jeff
  • free black on white stories
  • lesbian movies names
  • japanese girls doing anal
  • lesbians have an orgasm rate
  • picture of asian bride
  • Human sex photos
  • amatur couples having sex
  • nudist beauty contest young girls
  • hardcore redheaded
  • linda friday free sex pics
  • russian couple sex video
  • all girls like anal
  • sexy ashley girl
  • erotic videos for lesbians
  • janey janes video
  • creation of pussy pic
  • how to give girls an orgasm
  • sex group threesomes
  • young chicks beaches
  • teen boys nude pics
  • wild sexy babes videos
  • girl dildo shaved pussy
  • horny wife in the morning webcam
  • Lesbians teens fingering ass movies
  • young and mature videos
  • bare black breasts
  • My ass sex
  • berlin sex and swingers clubs
  • Anal sex video gallery
  • mature black women pics
  • happy teenage girls
  • naked big boobed cartoon girls
  • mature hungry for anal
  • hot young fat girl
  • best orgasm sites
  • brazilian pussy indian
  • Lesbians licking their boobs
  • hot pussy hard cock
  • Naomi ryan sex scene
  • Naked ladies in public
  • suck trannies dick
  • free pussy lips gallery
  • brutal sex movies free
  • teen fuck buies torrent
  • omg huge dick sex
  • picture of in bikini
  • tila nguyen sex fuck
  • wet pussy sex
  • naughty lesbians lick titties
  • black monster teen
  • girl attacked
  • boys and mature sex vids
  • petite teen on top
  • Sneha hot boobs
  • little ebony girl masturgating
  • sex video monster ball
  • full free video sophie dressingroom sex
  • free blowjob video downloads without membership
  • all tubes kylie teen anal
  • big huge tits free sexy
  • brooke hunter open pussy
  • shower fuck movie
  • girl scout cookie pics
  • telugu bhamalu erotic xx movie tube
  • ass traffic xxx
  • meaty black pussy
  • butt anal white
  • pictures of tyson chandler and wife
  • Sex at public place
  • rate y tits videos
  • tunes the best erotic c
  • single asian girl
  • virgins no longer videos
  • mature woman free movie
  • self pic pussy
  • latinas anal
  • penis showing pussy girls girl
  • Ray j and kim kardashians sex video
  • Beautiful lesbian teen
  • husben wife black men
  • Meg white nude video
  • Sex videos of college girls
  • boys young teen video
  • teenage pussy tits
  • lesbian sex myspace layout
  • hayatabad sex videos
  • super young galleries
  • free mature hairy pussy videos
  • amateur auditions teen
  • streaming skinny russian sex videos
  • cute girl fingers herself until orgasm
  • brazil amateur teens
  • mischa barton topless movie
  • skinny mature videos
  • free teen young nudes
  • teenage girl bottle feeding video
  • Brazilian big ass
  • pussy toying orgasms girls only
  • asian latex pics
  • Kristin davis sex pic
  • phoenix marie army girl pics
  • young teen artistic nudes
  • hot and sexy ass
  • magicmovies big tits
  • watch young kitties movies without download
  • lesbian sex strap on movies
  • amazing cumshots free tube
  • nude pictures of teen girlfriends
  • justice league hardcore
  • young blonde dikes
  • vintage pin up girl pictures
  • tricked stupid girl into fuck
  • free ebony lesbians movies
  • young black teen girls having sex
  • Milf lesbians movies
  • mature facial cum movies
  • Couples nude video
  • sister videoed naked
  • lesbians sucking huge tits
  • best deep throat video lina loveless
  • Asian gigantic tits
  • black girl trailer
  • asian girl and
  • asian fetish pussy wet
  • Couples swap sex
  • nude flashing girls
  • jamie eason naked movie
  • free long tube mature videos
  • kardeshian sex video tape
  • asian girl gets butt fucked
  • free mature adult videos xxx
  • fucking poor black girls
  • free real amateur home sex videos
  • Teen pussy fisting
  • free young lesbian
  • tiny butt fuck girl
  • couples seducing teens sophia
  • jovans naked wife
  • Anal sex video preview
  • kink long stream video
  • black japanese trapdoor pond snails
  • camwhore blackmail tits
  • meet sexy little girls
  • uber sex pics
  • hot babe rubbing her pussy
  • close up sheer panties wet pussy
  • black beauty gallopping home
  • Unusual sex pictures
  • nude sexe video free mature
  • iive video teen
  • classic videos taboo
  • sora aoi topless pics
  • video girls sex tapes
  • hot blowjob movies
  • naked pictures of matt damien
  • amateur lesbians on video
  • nude younger girls free
  • Asian teens with big tits
  • motorcycle babes pictures
  • Group sex photo galleries
  • redhead teen nude xxx
  • amateur house wives home videos
  • pussy with penis inside
  • sex positions amateur
  • White teens outdoor sex on
  • online black and white galleries
  • teen blonde cunt
  • Nude fucking photos
  • Gangbang sex picture
  • young home vids
  • xxx audio sex
  • old man lick pussy