Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Shlomi Fish (918)

Shlomi Fish
  shlomif@iglu.org.il
http://www.shlomifish.org/
AOL IM: ShlomiFish (Add Buddy, Send Message)
Yahoo! ID: shlomif2 (Add User, Send Message)
Jabber: ShlomiFish@jabber.org

I'm a hacker of Perl, C, Shell, and occasionally other languages. Perl is my favourite language by far. I'm a member of the Israeli Perl Mongers, and contribute to and advocate open-source technologies. Technorati Profile [technorati.com]

Journal of Shlomi Fish (918)

Tuesday April 17, 2007
11:15 AM

The "Knowledge in the Ether" Anti-Pattern

[ #33013 ]

One anti-pattern I noted in a previous workplace was what I called "Knowledge in the Ether": most of the instructions for getting the application up and running, and a lot of the collective knowledge were not written down in a collective place. TDDPirate said he was familiar with it and called it the "Oral Torah" syndrome.

The solution for this is simple: set up a wiki for the company, and instruct people to write a note there whenever they need to explain to someone how to do it (or give a link to a previous note), instead of guiding him how to do it. While this requires some discipline and getting used to, it can also be done after the fact.

Obviously the amount of knowledge in people's head and in the Ether can never be completely eliminated. But it should be kept down to a minimum.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • ...and then you automate.

    Make sure part of the documentation process is typing it down in a scripting language.

    Start out by just solving the immediate problem, then extracting out utility libraries and configuration patterns (make sure you do this, otherwise it will just end up being a mess of hardocded crap).

    Soon it will be easier to script it than to document it.
    • Yes, you're right. But documentation in a wiki still has its uses, including to point to the right script to use.