Helpful support instructions



  • We're about to deploy a new system (that's been in the works for 2 years) for the first time. We hired a team of folks to support it 7x24 so we don't have to get called in the middle of the night. One of the junior programmers is tasked with writing the support manual. The entire troubleshooting section consists of (exact quote): Scan the log files looking for problems, fix the code, and re-run the process.

    Now these support folks are not developers, had no part in designing or building this system, and have no access to source control, the development environment, or anything, nor should they, so they have no clue how it works. I suggested that perhaps a bit more detail was in order, or in lieu thereof, that this developer's home phone be listed right in the manual as the first contact for any problems they can't fix by following the instructions in the manual.

    In self defense, I decided to write my own manual (currently 60 pages and growing) that contains examples of everything that we've seen go wrong (symptoms, sample stack traces, what to look for and where to find it, and detailed step-by-step instructions for correcting, including contacts at the remote systems that can leave us hanging). I needs my sleep!

    Sheesh.

     



  • Assembly Instructions:

    1. Get Parts.
    2. Assemble.


  • A lot of times when you suggest them putting a phone for a developer down, they'll just put your number down.

     Goodbye sleep.



  • @snoofle said:

    One of the junior programmers is tasked with writing the support manual.
    There is your problem. Technical authors exist. Hire one. Getting a programmer to write the manual is like using an image editor to write a letter. Sure, it'll _work_, but it'll always be a second-best solution.



  • A JUNIOR programmer writing the manual for the system you have been working on for two years? If you have been working on it for two years, why did nobody ever figure "we might need a manual?"

    Then you let a junior, one with limited experiance, write a manual. Doesn't sound too wise to me.

    Then he does he job not so wel, you find 'errors' in his manual, and instead of giving him some assistance so he can do his job better, you do his work for him. Making you pissed of for having more work, him pissed of for doing something 'useless' work now. Or leaving him clueless about him doing a bad job.

     Who is WTFing where?
     



  • @Cyrus said:

    Assembly Instructions: 1) Get Parts. 2) Assemble.

    Usage Instructions:
    1) Plug in.
    2) Use.

    NB: Plug not included.



  • @The General said:

    @Cyrus said:

    Assembly Instructions: 1) Get Parts. 2) Assemble.

    Usage Instructions:
    1) Plug in.
    2) Use.

    NB: Plug not included.

    Usage Instructions:

    1) Pull pin.

    2) Throw.

    Usage Instructions:

    1) Aim away from face.

    2) Pull trigger.



  • @MasterPlanSoftware said:

    @The General said:

    @Cyrus said:

    Assembly Instructions: 1) Get Parts. 2) Assemble.

    Usage Instructions:
    1) Plug in.
    2) Use.

    NB: Plug not included.

    Usage Instructions:

    1) Pull pin.

    2) Throw.

    Usage Instructions:

    1) Aim away from face.

    2) Pull trigger.

    Open Bag. Eat nuts.



  • @MasterPlanSoftware said:

    Usage Instructions:

    1) Aim away from face.

    2) Pull trigger.

     

    ow me foot



  • @snoofle said:

         One of the junior programmers is tasked with writing the support manual. The entire troubleshooting section consists of (exact quote): Scan the log files looking for problems, fix the code, and re-run the process.

    Now these support folks are not developers, had no part in designing or building this system, and have no access to source control, the development environment, or anything, nor should they, so they have no clue how it works. Sheesh.

    Sheesh indeed, where do you expect the junior programmer with no experience with the software, no access to the source or dev environment to get the detailed information on how to use and troubleshoot the system?

    Reminds me of our company.  We hired a bunch of young people for our QA group.  QA testing consists of them sitting and watching us developers test the software.  It doesn't just waste man-hours, it charges double the man-hours to each project for QA testing.  Which is really peevesome considering half of the manhours are for these kids to sit and drool.

    (I'm not opposed to new people.  I'm opposed to throwing new people into the deep end and letting them look stupid.)


Log in to reply