Documentation disaster



  • One of our directors has decided that all our projects' install, build and deployment processes are to be documented. I've just been moved to a new project (which is rather lacking in docs) and hence was a supporter of the idea - untii I found out that I'm supposed to write the deployment doc for said project.

    On an entirely unrelated note, I'm looking for a new employer.



  • @The_Assimilator said:

    One of our directors has decided that all our projects' install, build and deployment processes are to be documented. I've just been moved to a new project (which is rather lacking in docs) and hence was a supporter of the idea - untii I found out that I'm supposed to write the deployment doc for said project.

    On an entirely unrelated note, I'm looking for a new employer.

     

    I'd like to think that I'm usually one of the more benign folks around here - but seriously: You're complaining because your employer actually wants to have documentation on important processes? I can understand why your personal preference may be against having to write said documentation, but I would hardly call this a documentation disaster.



  • Technically the unititiated are the best people to write documentation, provided they have someone to ask questions when they get stuck, as they are the least prone to leaving out vital pieces of information because they're "obvious".



  • @Lingerance said:

    Technically the unititiated are the best people to write documentation, provided they have someone to ask questions when they get stuck, as they are the least prone to leaving out vital pieces of information because they're "obvious".

    Agreed.  However, I've found that the uninitiated almost never feel comfortable doing this - only those who aren't morons ever understand what is being requested, and even in the non-moron population, only a few understand it initially.

    Failing being able to get an uninitiated person to do the documentation from scratch, I find it works well to have an initiated individual write up a quick "attempt" at documentation, which may lack all vital information, but at least provides a partial skeleton for real documentation.  One hands this to the uninitiated person, and directs them to "Identify all gaps in what the document covers.  Ask the more experienced people for the information to fill those gaps, and update the document.  Not only will this give you a better understanding of what we do here, but you'll also get to know all of the key players and what they do."

    But the real sadness about this whole concept is I once interviewed a guy who had been through this at three different companies in a row, and he never understood why he was asked to do the documentation.  (We didn't hire him; we were, at the time, looking for someone uninitiated to write some docs for us; while we did at least have an attempt from the guys who developed the processes documented them (quite possibly the worst case scenario, because everything's obvious), we didn't want to put this guy through yet another round of confusion.  Since a quick explanation during in the interview didn't work, we didn't feel he'd eventually get it.)



  • So what I'm getting from this is you want documentation for a project you're working on but you don't want to write it? That's like saying you need an umbrella cause it's raining out and then complaining you're getting wet cause you don't want to be the one to buy one....



  • @apaq11 said:

    So what I'm getting from this is you want documentation for a project you're working on but you don't want to write it? That's like saying you need an umbrella cause it's raining out and then complaining you're getting wet cause you don't want to be the one to buy one....

    As long as we're doing analogies...No it is more like he doesn't want to be the one to manufacture the umbrella.  I bet he'd be willing to buy one.



  • Unless you're being asked to write up all the missing parts of the documention then I too fail to see the WTF in this.  You're charged with doing the deployment, document the damn thing as you've been told to do.



  • [ emphases mine ] 

    @The_Assimilator said:

    One of our directors has decided that all our projects' install, build and deployment processes are to be documented. I've just been moved to a new project (which is rather lacking in docs) and hence was a supporter of the idea - untii I found out that I'm supposed to write the deployment doc for said project.

    So TRWTF is that you weren't careful what you asked for.  And got it.


  • @DaveK said:

    [ emphases mine ] 

    @The_Assimilator said:

    One of our directors has decided that all our projects' install, build and deployment processes are to be documented. I've just been moved to a new project (which is rather lacking in docs) and hence was a supporter of the idea - untii I found out that I'm supposed to write the deployment doc for said project.

    So TRWTF is that you weren't careful what you asked for.  And got it.

    I am a supporter DaveK, everyone else should send him presents.


Log in to reply