Slashdot Mirror


Institutional Memory and Reverse Smuggling

An anonymous reader writes "Anyone who's worked in a large engineering firm is familiar with institutional amnesia. Things get built, and then forgotten. Documentation is supposed to help, but rots, is lost, or uses obsolete methods and notation nobody understands anymore. I recently found myself in a strange position, rehired as a consultant with the unofficial job of reminding the company how an old plant works. I even have some personal copies of documents they seem to have lost, which I have to awkwardly smuggle back in. I don't find these kinds of experience written about often, but I'm convinced they're more common than you'd think."

63 of 312 comments (clear)

  1. This problem is quite common. by ksd1337 · · Score: 5, Insightful

    A very relevant area where this problem can be readily seen is computer data formats.

    1. Re:This problem is quite common. by YayaY · · Score: 5, Insightful

      Yep, It happens all the time everywhere.

      What I find most troubling about this is that most company don't recognize the problem or are not even aware of it? I think the mentality that "anyone can be replaced so we don't have to create incentive to retain them" is going a bit too far.

      Because the real problem is in fact employee turnover.

      --
      Votator.com implements a fair voting scheme (free
    2. Re:This problem is quite common. by Altrag · · Score: 3, Insightful

      Because the real problem is in fact employee turnover.

      When you're talking about a scale of decades, including economic downturns with hiring freezes and whatnot, employee turnover is a fact of life. No one works in the same place forever, no matter how good the incentives are to stay. Even if you can stop them from changing jobs, they might retire. Even if you manage to make their job so compelling that they don't retire, death will eventually get them. And good luck getting ghosts to work for you in any meaningful way.

      Its purely a management problem. Data retention over long periods of time is a real challenge, and one that most people don't care about because well.. out of sight, out of mind. Put a token effort towards data management when someone important is looking (investors, higher management, whatever). And then redirect the money to more immediate problems as soon as the heat is off.

      Remember, the quarterly report is king. Trying to predict and prevent problems that may or may not crop up 10 years from now seems less relevant when you have to make not only profits, but record profits year after year or risk your stock price plummeting.

    3. Re:This problem is quite common. by turbidostato · · Score: 4, Insightful

      "Because the real problem is in fact employee turnover."

      That's not as much a problem as a reality you'd better learn to live with.

      Look: there's only two ways for an employer-employee relationship to end up: either the company closes business or the employee goes out. Since the company as an entity isn't so interested on the afterthoughts of its own end, there's only an interesting case to consider: the employee will go away. That's as valid for the janitor as is for the general manager.

      So it is not "anyone can be replaced" but "anyone *will* be replaced".

  2. Been there, done that: by Hartree · · Score: 5, Funny

    But the NDAs keep me and everyone else involved from talking about it. :P

  3. Absolutely true by cvtan · · Score: 5, Interesting

    I have personally witnessed this happen with my former employer. Higher ups seemed to think that there was some benefit to the company "memory" or "team experience" if we almost brought a product to market. People would argue that at least we now had the experience to do this again in the future if we had to. Totally wrong. Teams were broken up and key players re-assigned. Some people left the company or moved to divisions physically remote from their former bosses. Any reports written could not be used to replicate anything useful and, to be honest, who would write a report explaining the history of an unsuccessful product? It never happens. Real knowledge is lost in a barrage of wasteful spending.

    --
    Sorry, but gray text on gray background is making my eyes bleed.
    1. Re:Absolutely true by Mr+Z · · Score: 3, Informative

      Where I work, we've mined many products which failed to reach the market for good ideas. Often, there were many good ideas in there, it was just the package as a whole that didn't work out. (Either too early, too late, too big or too small.) But, we've also had good continuity among our key folks (myself included), so that probably explains why it ends up working. We understood why we put those features in failed product X, and so we understand how they'd work in new, more viable product Y. We also understand at least something about why X failed, so we can try to avoid it on Y.

      But again, that does rely on institutional memory to make it work.

  4. I see this in code I work on all the time by NotSoHeavyD3 · · Score: 4, Insightful

    Somebody writes the code, doesn't bother to comment it at all and then you come in years after the fact. You look at the code and wonder, "why did he do it that way instead of this way?" Then the big gotcha, you think I could ask him but he left the company 5 years ago(At this point slap your forehead and hope you don't break anything working on the code.)

    --
    Did you know 80 to 90% of the moderators on slashdot wouldn't recognize a troll even if one dragged them under a bridge.
    1. Re:I see this in code I work on all the time by ninetyninebottles · · Score: 4, Interesting

      Somebody writes the code, doesn't bother to comment it at all and then you come in years after the fact. You look at the code and wonder, "why did he do it that way instead of this way?" Then the big gotcha, you think I could ask him but he left the company 5 years ago(At this point slap your forehead and hope you don't break anything working on the code.)

      One way to mitigate this is "extreme programming" where developers pair and constantly switch off projects and tasks. You end up with a larger body of people that understand the code and comments and code that is much more understandable because if you write it in a way that isn't, someone will notice the next week, complain and you have to go back and fix it.

      Also, if you're hoping you don't break anything, hopefully you have a battery of unit tests and functional regression tests that will catch the lion's share of anything you might break and let you know in short order.

    2. Re:I see this in code I work on all the time by Anonymus · · Score: 5, Insightful

      Even worse, it sometimes turns out that YOU wrote the code 10+ years ago, and you have absolutely no clue why it was written that way.

    3. Re:I see this in code I work on all the time by zill · · Score: 4, Funny

      You guys have it easy. Sometime when I write a comment I for-SQUIRRELS!

    4. Re:I see this in code I work on all the time by heypete · · Score: 4, Informative

      It's a reference to this scene from the Pixar movie "Up".

    5. Re:I see this in code I work on all the time by v1 · · Score: 5, Interesting

      hopefully you have a battery of unit tests and functional regression tests

      Or just plain boobytrap the code all over the place with sanity checks and known gotcha conditions, spiked with good comments and explanations.

      I ran across that just last week when developing an importer for iTunes music library - reusing an xml class I wrote 3 yrs ago, it blew out on me with a "you're being STUPID" sort of error message just under a dozen times during development. Opening up said code block revealed comments I made when I wrote the sanity check, describing WHY it had coughed up the message, and more importantly, what was causing the problem.

      I of course had little to no memory of ever writing them, but there they were, providing me an instant catch-me-up in the why's of my code, and saved me from having to relearn all the internals and subtleties that went into writing that bug-free, beautiful, and time-saving class of code.

      That's one of the great things about having a poor long-term memory - it forces you to comment (and liberally sanity check) your own code well, not because someone else will need it, but because you are going to need it. You get to be the direct beneficiary of your own good practices.

      --
      I work for the Department of Redundancy Department.
    6. Re:I see this in code I work on all the time by Eristone · · Score: 3, Funny

      A post at bash.org:

      //
      // Dear maintainer:
      //
      // Once you are done trying to 'optimize' this routine,
      // and have realized what a terrible mistake that was,
      // please increment the following counter as a warning
      // to the next guy:
      //
      // total_hours_wasted_here = 25
      //

  5. I have to remind of solved problems by gestalt_n_pepper · · Score: 5, Insightful

    I design automated testing systems. I find myself in the position of re-solving problems that were solved as much as 10 years ago in prior automated testing systems. There's an odd tendency of people to simply passively accept whatever the manufacturer of the new system gives us as somehow "better" or more advanced that what we had, even when the new solution is an obvious fail, or (ahem) undeveloped. So I fix things to make up for the shortcomings of the new software, more or less the same way I fixed them 7 to 10 years ago. Things start working again. Everybody is happy.

    I seem to have discovered job security by re-inventing the same thing every 7 years or so in a slightly different form using a different programming language. Of course, that sort of describes the entire computer industry, more or less.

    --
    Please do not read this sig. Thank you.
  6. Why bother by Anonymous Coward · · Score: 5, Insightful

    Why bother trying to smuggle them back in. Tell them you'll work on figuring out the bits you can't remember and will write a new manual. You get to charge them for time you don't need to spend and avoid getting caught.

    1. Re:Why bother by Trepidity · · Score: 5, Insightful

      In this case it really is the safest solution, though. Companies don't want to know that someone has violated their precious document security policies, and would be much happier overpaying to have the data recreated than finding out that someone had a private copy. This guy giving engineers copies of the documents is probably the nice thing to do, but it's a risk that the incentives don't favor. Either he's naive, or knows the engineers he's dealing with well enough to trust that nothing will happen.

  7. Software Evolution by Anonymous Coward · · Score: 3, Interesting

    One of the courses of my university study was called 'Software Evolution' in which tutors showcased all kinds of problems with legacy software. Software using languages or platforms no one knows about anymore or lost source code of mission critical systems. Especially older banks and insurance companies suffer from this problem, often choosing the 'wrap around the bit that we know that works' instead of a complete overhaul of a system no one really knows what it does but does it really well. I fear everything we build today will cause the same problems, but worse. Perhaps the old idea that readable code should help people understand its function saves us from this scenario...?

  8. Dear Slashdot admins, by sootman · · Score: 5, Insightful

    More like this, please, and less about the Apple/Andoid/MS/Samsung/**AA suit-of-the-minute. I know, I know, flamewars == pageviews == Step 3, but you've occasionally gotta throw something out there for us old-timers.

    --
    Dear Slashdot: next time you want to mess with the site, add a rich-text editor for comments.
    1. Re:Dear Slashdot admins, by Anonymous Coward · · Score: 5, Insightful

      How about you submit more like this? Or create more like this? Or find a site that is more about this? Or make a site that is more about this? I'd love to see it too but the fact of the matter is that the majority of the people here don't have these kinds of problems nor are they interested. Wait and see. Give this article about 3 days and look at the next closest article about Google/MS/Apple/RIAA and see what gets what comments. Granted, this article will probably get more insightful and thought out comments and a lot less of the memes and trolls than the others but page hits is what the management wants. They don't really care about content.

  9. Outside of the code, all documentation is worthles by cavehobbit · · Score: 5, Insightful

    I currently work for a company that has instituted an incredibly restrictive development methodology they bought from a big consulting firm. It requires multiple forms be filled out for every program written, every requirement for every program written, every request for every change to every program or application written. All of these reviewed by coworkers who are not about to alienate team members, and reviewed by lower management who want to look good to upper management by having everything go smoothly.

    These documents are then stored on the LAN. To never, or rarely ever, be read again.

    The one thing it does not enforce or require, is meaningful documentation in the code itself.

    It doubles, or more, the time it takes to do everything. But it does nothing to stop the mistakes any better than the procedures that went before. If anything, it finds less errors, because we were not given more time to do this double or more amount of work. So time is so compressed, we do not have time to do anything other than get it working and get it in.

    One thing it does do very well, is prevent problems from getting fixed. The only people that will start a change effort are those that notice a problem and are affected by it enough to have it cause them problems. Otherwise no one wants to go through the bureaucracy to kick off any sort of change effort, which leaves a lot of ticking time-bombs in the infrastructure configurations, application designs and application code.

    The only place documentation is good, is if it is meaningful, and in the code, where it is readily findable and far less likely to get lost, short of some fool deleting it.

    Documentation located anywhere else will be lost, or obsolete many more times than not, before you ever really need it.

    If anything, documentation in code should be reviewed by people with absolutely no connection to the application it is for. If it is good enough for them to figure out an understand what is being done, and more importantly why it is being done, only then is it worth anything more than the bytes is written with in storage.

  10. Opportunity for more pay by mbone · · Score: 4, Interesting

    I recently found myself in a strange position, rehired as a consultant with the unofficial job of reminding the company how an old plant works.

    I certainly hope that you negotiated a much higher salary than before.

    I have known people who were fired in a "chain saw" maneuver who proved to have core corporate competencies in their heads. They negotiated for a much higher rate the second time around...

    1. Re:Opportunity for more pay by Nidi62 · · Score: 3, Insightful

      If you RTFA, you would know if s/he did.

      If you had read it, you would know whether to use "he" or "she".

      --
      The only thing necessary for evil to triumph is for it to be pitted against a slightly greater evil
    2. Re:Opportunity for more pay by Anonymous Coward · · Score: 5, Funny

      I know a guy who, after the company was bought, got the ax along with every other engineer in the place.

      As he was working remotely, he had a local copy of the entire repo. With his severance check was a reminder to "destroy all company information in his possession".

      Fortunately, he didn't do that because, 2 months later, they came back asking if he had gotten around to doing that because the salesdroids accidentally sold off the main repo server when they liquidated the office equipment.

      He greatly enjoyed negotiating the fee for "recreating" the repo that he "didn't have".

  11. Company rules against removing documents by blackC0pter · · Score: 5, Insightful

    I'd be very careful in this situation. Even though you are supposedly "doing the company a favor" by smuggling the documents back in, were you even legally allowed to take the documents in the first place? Most employers have contracts or rules that state you can't remove documents from the office or that when you leave the company you must return all property to the company. Furthermore, it is most likely that this documentation was property of the company all along and in that case did you break any laws by removing it from the company and keeping it? IANAL but this is a very tricky situation. You may be doing good for the company now but you are profiting off of documents that you do not own and may not even have a legal right to possess.

    Personally, I'd stick with just what's in my head and not keep any documents, files, etc. from a previous employer. It's just asking for trouble.

    1. Re:Company rules against removing documents by Anonymous Coward · · Score: 5, Interesting

      Yes, that's what makes it tricky. I wasn't supposed to have these documents, but some important internal drawings have been lost, and I have a copy. The safest solution would be to avoid bringing it up, I agree. Though I'm not blackmailing them for the documents or anything.

      I've heard it happen several other times. I've had colleagues who consulted for a company, then a few years later get a call or email asking if they by any chance still have a copy of some old document. Of course they weren't supposed to have kept a copy, but if they accidentally did, it would be really nice if they could send a copy because the company seems to have lost it...

      It mostly happens at lower levels of the org chart on a don't-ask/don't-tell basis I think. Lots of people keep personal archives, and sometimes the official archives have to get patched out of them.

  12. Aliens. by mosb1000 · · Score: 5, Funny

    If the history channel read this story, they would undoubtably conclude that the plant was built with the help of aliens.

  13. Documentation is key by markdavis · · Score: 4, Insightful

    My situation is different, yet similar. I just have so much responsibility for so many things at work, I simply can't remember how everything works. At times it is frightening, especially since year after year there are more things happening and I get older, so it is already inherently more difficult.

    I also find myself "protecting" my sanity by almost intentionally forgetting how some things operate, especially those things I don't like.

    I think as a manager, one of the most important things to do is learn to effectively document everything. I always knew documentation was important, to the point that I have a log of everything I do at work, every day, that spans 23 years! But those are just "reminders", not proper documentation. It helps to jog memory or memorialize certain facts for reference. Nothing replaces *proper* documentation, though- the kind that is well thought-out, has great detail, and is organized properly. Further, it will have insights into defining the problem and the solution and WHY you selected certain paths and not others.

    Proper documentation takes considerable time, and many people think it is a waste of time, especially when one is drowning in projects and deadlines. When you reach the point that you can't handle the load without continuing to document properly, you know you are in trouble. In the short-term, you can "win" by getting more things done. But in the LONG TERM, you are basically screwed, because you will spend a tremendous amount of wasted time later trying to relearn what you did and why. Or worse, trying to defend your decisions and can't because you can't find the information, it doesn't make sense, or it just doesn't exist.

  14. Control is the problem. by mosb1000 · · Score: 3, Insightful

    The bean-counters and mindless penny pinchers who run most corporations like to keep everything secret and proprietary without fully appreciating the costs associated with maintaining that level of secrecy. The solution is simple, only keep something secret if you've first: taken the effort to understand what it will cost to do so and second: taken the effort to make sure the secret won't actually be forgotten. In short, keep fewer secrets, and keep them a lot better.

  15. I don't comment my code anymore by MichaelCrawford · · Score: 4, Insightful

    i did so slavishly at first but then my boss pointed out that comments are rarely updated with the actual code. a contrived example:

    int foo()
    { // always returns 4

          return 5;
    }

    now I have a coding style that the simplest fool can understand. that's quite a different thing than the arrogant coders who feel that their colleagues are incompetent if they cannot follow uncommented code. if someone cannot follow my code then I feel I have done something wrong, not them.

    --
    Request your free CD of my piano music.
    1. Re:I don't comment my code anymore by UnknownSoldier · · Score: 5, Interesting

      > that's quite a different thing than the arrogant coders who feel that their colleagues are incompetent if they cannot follow uncommented code. if someone cannot follow my code then I feel I have done something wrong, not them.

      IMO, _proper__ commentting discusses WHY you did something. If someone wants to understand HOW it was done, read the code, as you correctly reason. Any half-decent coder should be able to figure out what the code is doing.

      EXCEPTION: If you are doing something tricky, then document that. i.e. http://www.codemaestro.com/reviews/9

  16. Old news by DingerX · · Score: 4, Informative

    Primo Levi, "Chrome" in The Periodical Table describes a similar problem with a paint formula at his factory in the 1950s. Evidently, during the war, they had a QC problem, included some chemical to correct for that, and the formula became a cargo cult, long after anyone knew what it was for. Someone changes some other factor, and their batch of paint gets the consistency of liver. So our hero had to reverse-engineer the trade secrets of a previous generation, back when he was working in the lab at Auschwitz.

  17. You haven't discovered job security by Colin+Smith · · Score: 5, Funny

    Until you write it in cobol.
     

    --
    Deleted
  18. this is why you shouldn't outsource by MichaelCrawford · · Score: 5, Insightful

    if your own employees do the work your company retains the knowledge of how to get it done.

    if you outsource you never learn how to do your own work, instead you finance your outsourcing firms efforts to learn how to operate your business. not only do you not gain that institutional memory but that outsourcing firm can now perform that same work for your competitors.

    --
    Request your free CD of my piano music.
  19. assertions are better than comments by MichaelCrawford · · Score: 4, Interesting

    now one does need to document the expected inputs and results of subroutines. better than commenting is to use assertions as well as unit tests. so for that contrived example, what I would actually do:

    int foo()
    {
            int result = 5;

            assert( 4==result);

            return result;
    }

    if you don't maintain the assertions and unit tests with the payload code you'll find out about it right away.

    --
    Request your free CD of my piano music.
  20. Re:It's common by brusk · · Score: 5, Funny

    Maybe if the company had given itself a name it would have been easier for it to keep track of information.

    --
    .sig withheld by request
  21. Re:Outside of the code, all documentation is worth by Anonymous Coward · · Score: 3, Insightful

    The only place documentation is good, is if it is meaningful, and in the code, where it is readily findable and far less likely to get lost, short of some fool deleting it.

    Deleting documentation is far more important than writing it. There is nothing worse than documentation that is clear, concise, convincing and that assumes something that is ever-so-subtly wrong due to the code base having been changed since the documentation was written. It's better to update the wrong documentation, but deleting it is far better than leaving it in in most cases. So no, people deleting comments are not necessarily fools, especially not if working to a deadline.

  22. No by Colin+Smith · · Score: 3, Funny

    Speaking from experience, corporations are unable to give themselves just one name. They have to change their names regularly (because it obviously makes things better, like go faster stripes) and more, they have to change the names of departments even more regularly (again because it improves everything). The result is that any documentation system which is created rapidly becomes fragmented, out of date and lost as the paths to the documents are changed to match the names.

    The conclusion is that using names only makes things worse.

    --
    Deleted
  23. Re:Sometimes IT has to help the business by TheLink · · Score: 4, Interesting

    Maybe some companies need a Historian or two.

    An important task for Historians is to regularly remind the bosses what Historians are for so they don't get sacked ;).

    --
  24. Perhaps small reusable components might help by Colin+Smith · · Score: 3, Insightful

    They could do one thing, just one thing, but do it well...

    Now... Where have I heard that philosophy before?
     

    --
    Deleted
  25. Re:NASA by 0123456 · · Score: 4, Informative

    NASA has lost ALL of it's Saturn V knowledge.

    Uh, no it hasn't. It may not be readily accessible, but there are (literally) tons of Saturn V information still available.

    The scientist have died, the documents have rotten and been lost.

    That'll be a surprise to the people who've put many gigabytes of Apollo-era documents on ntrs.nasa.gov.

    What they have lost is much of the software; the Apollo Guidance Computer software only exists because some of the programmers had old listings that were OCR-ed, and the Saturn guidance computer software seems to be long gone.. there are a couple of computers left that may still have the code in their core memory, but so far no-one has been brave enough to try reading it out since that's a destructive operation and if you screw up you won't get a second chance.

    Fortunately if someone was to try to rebuild a Saturn V they'd use completely new electronics and software anyway. Heck, it would probably have to run Windows...

  26. salvage and surplus by goombah99 · · Score: 4, Interesting

    At my institution we routinely buy back equipment from salvage yards it was sold to. But this actually makes sense. We clear out lots of old stuff rather than pack ratting it. It's a small price to pay for the convenience of getting stuff we need back.

    --
    Some drink at the fountain of knowledge. Others just gargle.
  27. Re:So what's the problem then? by 0123456 · · Score: 5, Insightful

    Management don't care, why should you? It really can't be all that much of a problem.

    The manager who didn't document anything finished ahead of schedule and below budget. He got a big bonus and moved on to another job at a different company based on his reputation for delivering early and cheap.

    The manager who comes in to organise an upgrade to that software ends up taking much longer than expected and going well over budget because nothing was documented in the initial spaghetti code. He gets fired for being incompetent.

  28. It is a solved problem by Bryan+Ward · · Score: 5, Funny

    Years ago people solved this problem but they didn't document their solution well, so here we are again.

  29. Know-how and know-why... by AliasMarlowe · · Score: 5, Insightful

    One of the uncomfortable truths (uncomfortable for MBA cost minimizers) is that know-how is between the ears. It is not in the manuals or specifications, which merely prove that their writers had the know-how. Even more important is the know-why, which is part of the institutional memory which also resides between the ears.

    I have witnessed some "technology transfers" where a set of working products was transferred with documentation, design data, and much background information to a group in another region (mostly EU/US transfers). The first group is then wound down or redeployed. The new group does fine at first, until a new version of a product is needed. Then they always make mistakes the original designers would consider childish or stupid. They don't know the why behind design decisions, and don't know what to avoid. In my experience, it takes 5-10 years to build a decent product design group from scratch. On the other hand, an existing design group will sustain itself by mentoring and guidance of new inductees by experienced members.

    The only successful technology transfer which I participated in was one where a few senior designers were transferred with the set of products they were responsible for. It was far from cheap in up-front costs, but it avoided the crises and financial disasters which afflicted the other transfers after a year or two.

    --
    Those who can make you believe absurdities can make you commit atrocities. - Voltaire
    1. Re:Know-how and know-why... by camperdave · · Score: 4, Interesting

      This is exactly right. I was employed at a company and I happened to be at reception at closing time. The receptionist pulled out a binder, and her fingers flew across her telephone. I asked her what she was doing. She replied that each night she would have to punch in a 30 button sequence to put the phones onto night service. The receptionist had forgotten the why of what she was doing. Anyways, after analyzing the button sequence, it turned out that the receptionist was redirecting the line pools of department A to the phones of department B. Department B was a 24hr department... at least it used to be. It turns out that both of those departments had been disbanded long before I started there. I reprogrammed the system so that all she had to do was press a single button.

      --
      When our name is on the back of your car, we're behind you all the way!
    2. Re:Know-how and know-why... by radtea · · Score: 4, Interesting

      One of the uncomfortable truths (uncomfortable for MBA cost minimizers) is that know-how is between the ears. It is not in the manuals or specifications, which merely prove that their writers had the know-how. Even more important is the know-why, which is part of the institutional memory which also resides between the ears.

      A quick perusal of this thread shows no mention of George O. Smith's story Lost Art, which emphasizes precisely this aspect of engineering knowledge. A couple of humans archeologists are digging in the Martian ruins and come upon an ancient Martian device with the manual, which proves to be almost useless until they have done the systematic experimentation to understand how it actually works.

      It was published in December, 1943, which suggests this kind of problem has been happening again and again for the better part of a century. Unfortunately the solution to it (value your people and don't treat them as interchangeable parts to be laid off the moment its convenient to outsource their work) is so completely counter-intuitive to the sociopaths who have always been the ones in charge of large organizations that it will never be implemented consistently.

      --
      Blasphemy is a human right. Blasphemophobia kills.
  30. Ask intel by Anonymous Coward · · Score: 3, Interesting

    One of the things they do very well is... no, not designing chips, they suck at that, but duplicating fab plants. Down to getting everyone that's gonna work in there up to speed before the plant is finished.

    The key is of course not to just build a plant. It's to build at least two plants, at least one in reality and one in the documentation. Fred Brooks (yes, exactly in his book _the mythical man-month_) explains how this works for software and computer hardware. It won't be different for processing plants, except of course that your production numbers are lower. But even with just one physical plant, you need full documentation on how to replicate it, with every task and every job described. And then, of course, you update the documentation along with any updates to the plant, bring it back up to the level where you can xerox the paper into reality again.

    The test is exactly that: Can we give this to another engineer and have him duplicate the thing from that? Yes, most software documentation fails that test and is utterly useless as api docs or user manual to boot-- as if those code monkeys don't even read what they wrote, the illiterate bums. And yes, you probably should check every five or ten years if it's still understandable. If that's expensive, well, you get to pay more thirty years down the line. Or you can start from scratch, if you prefer.

    Notwithstanding that this documentation archaeology an interesting excercise, but as TFA illustrates, it makes for rather schizophrenic situations, is way out of the usual corporate flow of how things normally go, cost a bundle, takes a lot of time, and is fraught with uncertainty. Care and feeding of the corporate library is future-proofing the IP assets, far more so than filling a war-chest with patents. It's about as sexy as caring for the backup tapes, but you have those too for a very good reason.

  31. "New and improved" disease by meburke · · Score: 3, Insightful

    Accounting, for instance, has been done the same way for almost 500 years, yet there are thousands of accounting packages available, written in dozens of different languages, even to run on the same hardware. Some programs (Quickbooks, for instance) have been "improved" beyond comprehension while still preserving their deficiencies and shortcomings.

    Once a problem is solved in programming, it should never have to be solved again. Most of the underlying code in computer systems is based on programs written back in the early days of digital computers. By adding the basic "components" together, more complex systems problems can be solved at a higher scale of interaction and complexity. So, scaling can be a problem. And, how the heck are we supposed to know where to find the original solution to the problem? (Note: There have been attempts to "hash" the common solutions and create unique, searchable identifiers, but I don't know what ever happened to those experiments. The ACM maintains and makes available a "library" of fundamental algorithims, but it is getting unmanageable.).

    Now the person coming in to review or improve legacy code has a "complexity" obstacle that prevents him from easily determining the purpose and scope of the code.

    In the digital world, programs work on data. Every digital program relies on sequence, alternation, and repetition. Many researchers (Djikstra, Jacopini, Martin and more) have shown that these are directly comparable to concepts in mathematical logic (sequential proof, decision rule, and quantification) and have demonstrated ways to "prove" programs correct. In today's world, we have the power to actually analyze programs, derive the structures, and prove the validity of the results at a meta-level (giving a nod to Goedel on the way). A meta system of this kind should discover what a program or system does, whether it does it correctly, and whether it does ONLY what it is supposed to. Now the problem becomes one of making the results understandable. The various packages that analyze source code and produce UML documentation are a very good start in that direction. I am concerned, because, (as recent demonstrations of Stuxnet and Duqu show) the interaction of flawed systems can have accumulating ill effects on those of us who have to depend more and more on computer systems to control our cars, our environment and the tools we use in our lives.

    Not every industrial process is as easy to analyze as software. And the complexity of modern industrial processes makes it even harder to understand once the process has been analyzed. Much of industrial behavior is analog; much of it is probabilistic; and much of it depends on uncontrollable inputs such as human behavior, and human mis-interpretation of the situation. If I was part of the investigating team trying to preserve lost company know-how, I'd probably go back to anything resembling requirements analysis, and work forward from there.

    --
    "The mind works quicker than you think!"
  32. labour relations by Ralph+Spoilsport · · Score: 3, Interesting

    Many companies have a tiny number of people who manage things, and then a sea of consultants who do things. Often the management of the consultant groups are consultants themselves.And even the managers of the managers are often consultants. The result? Corporate Memento syndrome. No long term memories get formed because the people who do the remembering are gone. Stuff is rar'd or stuf'd or tar balled into a series of docs that sit on a server than is run by an bunch of consultants in IT who have no idea what is on the drive.

    Then the drive either fails or is dumped into a bigger storage drive and labeled in a folder "management data 2009" or whatever, and there it rots because no one has any idea what's inside, and the people with access are consultants who don't/can't know.

    and why? Because it's cheaper to hire a river of consultants for 6 months than it is to hire people and keep them around for years. The result? Permanent amnesia. All of it will be lost, and no one will care. the essence of 21st century culture - digital business - will be erased and forgotten. Forever. Some would say "Good riddance", but I'm enough of an armchair anthropologist to feel the loss.

    --
    Shoes for Industry. Shoes for the Dead.
  33. Happened to me at NASA... by JetScootr · · Score: 4, Informative

    I worked 30 years in astronaut training facility (full-fidelity simulators), and wrote many many documents on software that I wrote. I always kept my own digital copies, of course. Over the years, the contracts changed hands many times, and different document systems were implemented, and "all" documents were "always" converted from old to new. I was never able to later re-locate *any* document I had submitted to *any* of the document systems. So my copies of my documents were the only ones that actually existed that I knew of. This included meeting minutes, peer review notes, design and 'as-delivered' documents. So I think institutional amnesia is more the norm, and actual memory beyond 3-5 years is rare.

    --
    Pavlov wouldn't be so famous if he'd used a can opener instead of a bell.
  34. Re:And so, civilisation ends. by Fjandr · · Score: 3, Interesting

    This is actually why the space program is in the state it's in. They can't build more heavy lift rockets because there is nobody left who actually knows how they were built in the first place.

  35. Re:NASA by DanielRavenNest · · Score: 4, Informative

    This is incorrect. When I was working for Boeing, who was contracting to NASA, I saw the Saturn V drawings with my own eyes, in the data repository building at the Marshall Space Flight Center in Huntsville, AL. They are punch card aperture cards, which is IBM style punch cards with a piece of microfilm stuck into it. If you need a paper copy, they print from the microfilm. There are about 3 million of those cards, filling stacks of drawers, with all the drawings and many of the documents in them.

    On the Space Station project, which I worked on for many years, we had a data vault at Boeing, which was literally a vault in the basement, where all the project data got copies stored, and we of course had to supply copies to NASA, who then put it in their repository. If there is one thing government is good at, is storing documents.

  36. I've seen it happen a different way by roc97007 · · Score: 5, Insightful

    I saw a company lose probably 60% of their IT knowledge base. They announced outsourcing six months in advance, and directed current employees to document their jobs so that offshore workers could take over. Employees instead used the time to find other jobs, as one would expect. Transition was a disaster, and a year later they're still discovering things that the company no longer knows how to do.

    One of the mistakes made was to assume that everything the old team did could be described as a procedure that a junior offshore employee could follow. This is a fallacy at a basic level, and shows a basic misunderstanding of IT. Knowledge is more than just memorization of individual procedures, it's information about topology, architecture, the flow of information, how the business works, and where the knowledge points are in the organization. (Who knows what.) Degradation of that knowledge base began on the day outsourcing was announced, and by the time transition arrived, there wasn't much left.

    The basic misunderstanding, I believe is thinking that IT is generic procedure-based stuff that anyone could do. There are cases where this is true, but if you are in the business of providing a web based business, your IT *is* your value add, and your success is probably based on in what way your team does things that *aren't* generic.

    --
    Oliver's law of assumed responsibility: If you're seen fixing it, you will be blamed for breaking it.
    1. Re:I've seen it happen a different way by brhalltx · · Score: 3, Informative

      One of the mistakes made was to assume that everything the old team did could be described as a procedure that a junior offshore employee could follow. This is a fallacy at a basic level, and shows a basic misunderstanding of IT. Knowledge is more than just memorization of individual procedures, it's information about topology, architecture, the flow of information, how the business works, and where the knowledge points are in the organization. (Who knows what.) Degradation of that knowledge base began on the day outsourcing was announced, and by the time transition arrived, there wasn't much left.

      I've seen the same. I took over a fairly large database project with distributed client software from a previous team. I had about a day to ask questions of that team. I learned most of it on my own; I added a lot of code comments, logging, and documentation as I went. The project was outsourced; they had 30 days of daily sessions and Q&A to learn the project. The team it was outsourced to supposedly had experience with this particular database (it has a client/user interface built on top of the database engine). They asked a lot of questions (all answered), received all of the documentation, had access to test servers for testing code changes, and managed to screw it up within a couple of days of taking it over. The support part of the team starting contacting me for help... After I'd been laid off. Not much I could do to help for free... They, of course, then promptly blamed me, claiming they hadn't been trained on whatever they screwed up. I heard it took them six months to get it straightened out again. You get what you pay for.

  37. Re:So what's the problem then? by DaveGod · · Score: 3, Interesting

    Sounds familiar. I work in accountancy practice. The first year someone does a good job, gains an understanding of the business, thinks about it, documents the prep file well and puts important long-term stuff into the permanent file. Takes say 100 units of time.

    Second year, someone does a good job, mostly gets to follow last year's files but keep up the documentation, updates it and the permanent file. Takes maybe 60 units of time, which sets a realistic bar.

    Third year, someone follows the previous year file but doesn't bother documenting their own and fuck the permanent file. Takes 40 units time and a pat on the back. Resets the bar at 40 units.

    Year 4, see year 1.

  38. History vs. Archaeology by DrVomact · · Score: 5, Interesting

    Management don't care, why should you? It really can't be all that much of a problem. More a perception than a problem. By all means go ahead and create/use a documentation system for your group but clearly there just isn't a requirement for anything more comprehensive.

    All too true. The sooner you learn not to care, the sooner you will stop feeling the pain. Surrender to mediocrity; obey all rules and your managers without question. Above all, do not let your work interfere with your life. You will be a happier person, and probably get promoted. Listen to me, oh young ones...heed the words of the Ancient One: Despair!

    Once upon a time, I worked in a relatively small organization within a Very Large Company. The VLC was renowned for its inventiveness, until a new manager came who felt that inventing things was much too expensive; it would be more profitable to just to put the word "Invent" on the corporate logo, and then re-sell stuff from countries who make things cheaply. Because our corporate logo was on these re-branded products, we must obviously have invented them. Thus, marketing ceased to be a partner of R&D, and instead replaced it. Clever, eh?

    One of my contributions to the VLC was a simple document management system (DMS). My boss mentioned that all the engineers in our lab kept complaining that "they can't find anything"—specifically, nobody could find old documentation for code that was written by vanished civilizations of programmers that had previously labored at the lab. In fact, it turned out that this was a general problem among the labs of the VLC, and that they all wished mightily for a solution. Apart from really ancient projects (from, say 10 years ago), it was pretty difficult to find documentation for even recent projects, as each lab had a different way of organizing its documentation, different document formats, and no channels for distributing the documentation to other groups who might have a legitimate interest. So I brought in an easy-to-use and easily maintained DMS, pitched it to the engineers at our lab, and got them to use it. My boss then made me contact a bunch of other labs, and offer them the use of the same DMS. A lot of their engineers liked it, and there was much happiness. I got lots of pats on the back for what was really a pretty simple idea, and my boss loved me for it. A year later, I was laid off.

    As I was the only one maintaining this system, and no one ever asked me to train a replacement, I doubt that this DMS—and its contents—survived, save perhaps as digital ghosts on some unlabeled backup media in a faraway storage cave. In a sense, I'm one of the perpetrators of information decay; I caused all the knowledge deposited in "my" DMS to get black-holed. Come to think of it, this is probably not a problem; I'm pretty sure they've laid off all the engineers by now.

    I understood very well that simply setting up a DMS was not the cure for the I-can't-find-anything problem. It was a beginning, at best. What was needed was a comittment by the organization as a whole to make sure the information continued to be available for as long as the company exists. Because engineering practices change, so do documentation practices; documentation technologies themselves change—not to mention physical storage media and data encoding. My DMS probably should have been replaced with something better by now (if it had continued in use), and that means someone would have had to plan the transition, and move the old docs to the new system. Maybe the best thing to do is print everything as hard copy from time to time, and hire a librarian to keep track of this backup.

    Considering how much has been said and written (and blathered) about "knowledge management", it's amazing how little attention is ever given to the temporal aspect of institutional knowledge. Every engineering company should have an Office of Knowledge that has as part of its responsibility not

    --
    Great men are almost always bad men--Lord Acton's Corollary
    1. Re:History vs. Archaeology by Hyperhaplo · · Score: 4, Interesting

      All too true. The sooner you learn not to care, the sooner you will stop feeling the pain. Surrender to mediocrity; obey all rules and your managers without question. Above all, do not let your work interfere with your life. You will be a happier person, and probably get promoted. Listen to me, oh young ones...heed the words of the Ancient One: Despair!

      This is the absolute truth. Learn it easy now, or the hard way as you are booted out the door. I know this from experience. It is very true.

      Meanwhile, I've done this. Actually, I'm in the middle of doing it again. I've thrown documents in the deep pit of the corporate Document Management System, however, I've tried to keep it all together by linking documents together by reference and hyperlinking. Fab stuff, except people keep saying that they can't find a thing without a link. *sigh* and this is for a mandated DMS.

      So, now, I'm doing it again. This time with 'newer' technology (which shall not be named here, but of course is "Quick") .. same concept.. just easier to do instead of plain HTML. And on it goes.

      Worst thing I have done is documented the system I used to admin.. I have been replaced by monkeys for whom management thinks is doing *my* job because they can follow basic documented procedures badly. However, I take secret delight that it is not *full* documentation - it is merely a how-to and a where-is than anything else. You could use it to maintain the existing system, but you still need to know how the system works... and why it works the way it does.

      I have been kicked, and badly. By The Manager, and Publicly no less.

      Yes, I am on my way Out (tm).
      Yes, I was paid to build and maintain this and other systems, so that is in the past and done. I did my job, and did it well.
      If these monkeys can't find the system documentation then it isn't my problem.

      Now I am sitting back and watching the system degrade. Processes I created and documented are being sloppily followed, some not at all. Highly paid 'technical' people are spending days doing what takes me hours. Management doesn't care. Management doesn't want to know. Unless the system is down and someone is screaming then it Does Not Matter. Even then it is a case of 'fix this little problem now and I don't care why'.

      What really sucks is that I am carrying quite a bit of useful information in my head.

      So, what I am doing now is secretly bundling up what I know, putting documents and information together, linking it where it can be found and putting it where someone who - at some point in the future - will be able to find it and who will need to use it. I wish that person luck and happiness. It won't be tomorrow, or the day after, not next week or next month. Next year? Perhaps. Most likely in 3 to 4 years from now, when they find out that these twits should not be allowed near computers, let alone be allowed to administrate systems.. then this will be needed.

      Until then, I am being paid. I am doing my job, and my primary job is to make the PHB manager happy.

      I can no longer read Dilbert. It's too depressing, because it is too real.

      --
      You have a sick, twisted mind. Please subscribe me to your newsletter.
  39. Re:And so, civilisation ends. by turbidostato · · Score: 5, Insightful

    "But of course, this would imply a corporation with the ability to see beyond the tip of its own nose, which is rare."

    The problem is not only corporate culture but societal.

    Say Big Corp A has in fact the ability to see beyond the tip of its own nose and then spares efforts to prepare for the next decade which, of course, impacts its bottom line for this quarter. At the same time, Big Corp B doesn't see beyond the tip of its own nose and this quarter's results look better than that from Big Corp A. Then, all of a sudden, everybody, *you included*, sell their stocks from Big Corp A to buy stocks from Big Corp B which makes Big Corp B even bigger while Big Corp A is not a big corp any more.

    Which, ironically, makes Big Corp B to be the one with the ability to see beyond the tip of its own nose because since Big Corp A is a big corp no more, its investment for the future is now moot and shouldn't have been done to start with.

    That's exactly why you see from time to time companies exploding basically out of nothing (say Google or Facebook) despite of the fact that other Big Corps near the business niche have much more than enough muscle to crunch them -their stockholders wouldn't allow for the investment. And that's exactly way you see those Big Corps investing much more in rising the bars for new entries with lawyers, IP, patents and lobying legislators than in real R&D.

  40. Re:So what's the problem then? by Anonymous Coward · · Score: 4, Insightful

    I have seen a lot of examples where the problem was not lack of documentation but rather that the available documentation documented the obvious things (this is a piece of paper) instead of this is the formula for turning garbage to gold. It is very important to document what the code accomplishes instead of documenting each line of code.

    Good
      document once a purchase order has been approved, prevent changes to the line items

    Bad
    instead of if the PO status = 'APPR' and the item number or price is changed, raise an exception.

  41. The Real Problem - Corporate Attitudes by Nom+du+Keyboard · · Score: 3

    There have been a lot of nice and informative comments to this point about the various facets and symptoms of the problem, but here is the problem itself: Corporate Attitudes.

    1: Companies don't give you time to write peer-reviewed documentation because that doesn't contribute to Time To Market and overall productivity.

    2: Companies seldom ask you to train your replacement in the I.T. world because they don't want you around once you realize that you're about to be laid off/fired. Who in I.T. hasn't had the experience yet of being marched off the property under the watchful eye of somebody (I've had it done where they guy actually carried a gun) within an hour of being told that you don't work here any longer. You find that you passwords were disabled during your 15 minute (at most) exit interview and given a box to clean out your work-area under guard.

    3: Most importantly, the corporate belief is that nobody is indispensable, and they're willing to prove it with you no matter how much you know that no one else does because the more senior that you were, the less anyone else was watching over what you did in the first place.

    In short, you're gone and they simply don't appreciate or value what they lost with you. And find this far more prevalent in I.T. than in most other areas.

    The flip-side is that you've probably also been hired at least once to pick up and complete an undocumented project of someone else that they previously let go. Isn't that fun?

    --
    "It's the height of ridiculousness to say for those 9 lines you get hundreds of millions."
  42. Re:And so, civilisation ends. by Fjandr · · Score: 3, Interesting

    I didn't say anything about "reinventing." I said building more of what they have.

    It costs a lot more to invent, test, and deliver something than it does to build another of something which already works. There's likely to be a lot of efficiency improvements with newer heavy lift rockets because of advances in technology. That has nothing to do with the point I made, which apparently went whizzing over your head.

  43. Computer Systems Too by trydk · · Score: 3, Interesting

    I used to work as a consultant for a very large, global computer manufacturer/consultancy as Solutions Architect. More than once I had to quickly find an available system to implement a customer's outsourcing solution as the normal lead time for a new system was 1 month+! (And before you start yelling "Virtual Servers", these customers required independent physical servers.)

    Sometimes I had to go through a list of servers on a specific subnet, match that up with a list of servers from the routine network scans to see if all were accounted for, if not, I would try to find the server in the server room, get its ID from the chassis, go back to the inventory system, try to find the server there and hopefully an owner too.

    Occasionally I could either not find the system in the inventory system or no owner was assigned. I would then have a private chat with the hardware people responsible for the area the servers were placed and suddenly the relevant servers would have an "unscheduled network outage", i.e. the operator would unplug the system and we would wait for somebody to start screaming. If that did not happen within a day or so, we would dump the system's data to the backup system and reassign the server. This time properly documented.