Document yourself out of a job

  • Comments posted to this topic are about the item Document yourself out of a job

  • I was working contract at a place where one person was the lynchpin to several projects.  He was a lead or manager and all of the facts needed to make decisions were in his head.  No one else could make design decisions because he didn't share.  I gave up early trying to get him to open up.

    Six months after I left, his car was hit and they had to put him into an induced coma for a month.  I think that it was several months after they brought him out before he had his full mental abilities.  I was sad for him.  But the company had to scramble to rebuild the knowledge he carried for a few projects.

    Another company had an Access application that we wanted to upgrade to SQL Server and .Net.  But the argument was that it was too complicated and only one person (nearing retirement age) knew how it all worked.  That last statement seemed to be the best argument for moving the application, but they drew the opposite conclusion  I think they finally after more than 10 years got permission when they changed the application that fed data into their Access database and all their imports would no longer work.

    Russel Loski, MCSE Business Intelligence, Data Platform

  • We have a guy who is general manager and chief engineer at a legendary local noncommercial college radio station that's been on the air since the '60s and has a huge metropolitan audience. This GM has been running all the daily and legal operations and fixing everything for more than 40 years. No one has any idea how to do what he does, or even the full scope of it, nor would any professional in the field step in and take over for the nominal salary the university pays this dude. And he's now in his late 60s. Whenever a succession plan is mentioned, he simply says, "oh, we have that in writing". But he won't say where or who can see such documents or anything. It's going to be a catastrophe when he does leave. In fact, the university will probably find it easier to throw their hands up and sell the license to NPR or KLOVE rather than bother with trying to find and hire a replacement. He thinks he's a huge asset to the station because he works so hard and has been so dedicated for so many years...but he's setting the scene for disaster. Reminds me of people who pay all their kids' bills well into adulthood and the kids have no idea how to survive when the parents are gone. Or people who think they're heroes for coming in to work when they're wick. I call it selfish valor.

    • This reply was modified 2 months, 3 weeks ago by  BrianWS1O.
  • One other thing, Kathi...I've been a contract programmer for more than 25 years, and most of the companies I've worked for do NOT want anyone to spend time on documentation. They may say so, but if you try to work on writing documents they say "we don't have time for that, do it later, right now we need you to work on" this or that production issue. Much like many businesses view QA testing. Slap it together, get it into production, we'll fix any problems when they come up. I even worked at one place where the project manager told the developers not to bother writing error handling routines because it took too long and we could just fix errors when the users complained.

  • In my opinion (after 40 years in the industry) the state of todays "documentation" is nothing short of dismal compared to what it was 20+ years ago.   The problem seems to stem from the fact that developers no longer take (or perhaps have) the time to document processes / code.  Instead, we now have “open source” - so go ahead and sift your way through a few thousand lines of code to get the answers you need, or hop on over to StackOverflow to see if someone else has already done the sifting or seen the error you are now experiencing.  My kingdom just to return to the basics! Simple things like what are minimum and maximum values this function handles, or what exceptions (if any) will be thrown when I call this function?  I spend the better part of each day researching HOW to use various APIs, tools, code, etc. – rather than (in days past) simply reading the documentation to find the proper function to call; there is a significant difference in workflow and it is not for the better.

  • I agree with you, Kathi. I'd like to add something to your discussion which I've only recently become aware of. Where I work, we've been experiencing a lot of people leaving. This is happening to many companies/organizations during the "Great Resignation". One of my coworkers on my team left a month ago. I like to stay in touch with coworkers after they leave, so I contacted him to chat after he had gone. He told me that he didn't have an exit interview when he left. Furthermore, because he was there for almost 20 years, he has seen a lot and knows the way where we worked operates. He knows that no one who leaves has an exit interview. I spent the last week he was there, peppering him with questions on a project he had been working on, because I was sure I'd have to take over for him. He said no one else asked him anything about the other projects he had worked on during his time there. I was shocked to learn that there was no exit interview. He worked on several projects there in all his time, but that knowledge just walked out the door when he left. What makes this worse is we don't have any formal means of documenting anything we work on. FWIW, I document the projects I work on in OneNote. I've no idea how my colleagues document (if they do) their work.

    Thinking back to when I first hired on to my current job, I was tasked with making modifications to a website, written by a guy who had left years before. I found only one document, which was a PowerPoint presentation the original developer had done, describing what the app was for. Other than that, there was no documentation. What made it worse is the original developer didn't use source control and his development machine was repurposed so there was no complete collection of source files, etc. It was a mess that took me a month just to get to a point where I could start making the necessary changes.

    Returning to my main point, in a LinkedIn group I'm in I asked if exit interviews were commonly done. I was surprised to learn that they aren't. One person, who lives in the UK, said that it is seldom done in the UK. He felt that it was more of an American practice. (I live in the US.) But even those who responded from the US, the majority work for companies/agencies that don't do exit interviews. No one really knows why. Most speculate that they thought the companies they work for just saw exit interviews as a way for the exiting employee to rant about the company. I see it as a lost opportunity to learn both about what the exiting employee knows and what has drawn them away.

    Kindest Regards, Rod Connect with me on LinkedIn.

  • I normally program by writing the comments/narrative first.  There's several reasons for this.

    1. Too many shops issue a vague set of specs. I make that clear in the code.
    2. On something with several moving parts and especially a project with several people with their fingers in the pie, I spell out exactly why it's done that way.  All too often it's due to inadequate responses, or none, from the relevant people involved.
    3. I need to keep track of the logic myself. There's far too many times I've been pulled off something for the latest emergency and may not get to revisit it for months or I get asked about it years later.
    4. I cannot depend of the documentation disappearing or someone editing it "by accident". So it stays in the code.
    5. When asked about something clearly documented in the code, I ask if they've looked. All too often they claim to have looked while the answer is in the first page of the document/comments.
    6. While this isn't practical for things like screen shots and the like, it's very easy to extract the comments and create the document.
    7. The code is versioned. Who maintains documents? I put my name on every document and request updates when changes are made. I've yet to receive any request to perform updates to any of my documents in years.
    8. Most importantly, documenting at the end never seems to be a great idea.  too much gets missed, possibly because you're sick of looking at that point.

    There's more but it saves me a lot of time to be able to look at the code and look at the comments without having to divert my attention to multiple screens or at the very least one more screen.

    Let's not get into a side discussion about people with only a hammer in their toolboxes and "cargo cult programming". I've ranted long enough.

    • This reply was modified 2 months, 3 weeks ago by  kfries.
  • Kathi/Brian, I was once hired as a SQL Developer by a company that turned out to be held hostage by an Oracle DBA/SQL Developer.  He would not share any information with me, despite my having been hired to do very targeted performance tuning of the application the company was trying to sell. This guy was all about being indispensable. He modified code in production on customer's systems, wouldn't use change control, and wouldn't explain anything to anyone. That job, the lack of an Oracle SQL Community and the amazing Microsoft SQL Community are the major reasons why I switched to the Microsoft Data Platform and haven't looked at Oracle in a dozen years.

    Rod, I have had only one exit interview in my nearly 50 year career that involved anyone technical. All the others were purely HR and they had no interest in any management or process issues I raised, they really just wanted a single sentence about why I was leaving (more money, more advancement potential, etc.).

    Brian/bdcoder, I have also found that no one either wants or is given the time to create decent documentation anymore. Almost no code comments, minimal check-in comments (e.g. "fixed issue #1234"), nothing but end-user documentation. Code reviews, if done at all, are not of any depth. What is the overall purpose of each SQL statement in this 4000 line stored procedure? No one knows but the guy that wrote it and left the project years ago. Agile never meant "don't document", it meant "document what's necessary as you go", but that's a nuance that got lost somewhere.

    Turnover in IT is high in general and even worse in many outsourcing firms, especially those outside the US and Western Europe. Any company, but especially those using contract developers or firms, need to insist on good documentation as a matter of business continuity. If you don't have time to document it, you sure won't have time to reverse engineer it when you need to add a feature, improve performance, or move to a new technology.

  • Another way to handle no-documentation-knowledge-hoarder is to simply let them know they can't be promoted until they've documented X, Y and Z. "Sorry - you're irreplaceable in your current role, so I can't assign you to anything higher paying"

  • I find I end up documenting tasks and issues more to help future me than anyone else.  I've been with my company for over 10 years now and there's a lot a knowledge stored in my head.  We also have a small-ish IT group here so I'm responsible for development, support of in-house and vendor applications, and some troubleshooting.  Some issues keep appearing (but not frequently enough to fix them).  And if I can't remember exactly how I fixed it the last time, I can look at notes I created, that my entire group has access to, or the script I attached to the previous ticket that shows what I ran to fix it.

    Helping future me can also mean helping future me enjoy an uninterrupted vacation.  Since the notes I have are accessible to my group, when I'm planning a vacation, I send my boss an email with recent issues and pointers to where the notes and scripts are.



    The opinions expressed herein are strictly personal and do not necessarily reflect the views or policies of my employer.

Viewing 10 posts - 1 through 10 (of 10 total)

You must be logged in to reply to this topic. Login to reply