Best way to write a troubleshooting guide?

Discussion in 'The Lounge - Off Topic' started by Big_nath, Jul 10, 2009.

  1. Big_nath

    Big_nath Kilobyte Poster

    397
    8
    44
    Hi,

    My manager has asked me to put together a troble shooting guide, it will include stuff like checking wireless in on, how to do certain things in some applications etc. At the moment we don't have anything. What is the best way to acheive this? We can't spend any money on new software. He said just type something up in word, but that seems a bit pants!

    Does anyone have any suggestions?
     
    Certifications: MCP, MCSA, MCSA:M, MCSE, MCTS
    WIP: A few
  2. Qs

    Qs Semi-Honorary Member Gold Member

    3,081
    70
    171
    Just type it up on Word. Keep it brief, bullet-point it and dumb it down.

    Imagine you're a user and you want to perform X task as easily as possible.

    It may be worth asking a couple of users some questions for a FAQ section at the bottom of the guide.

    Generally when I write guides I just follow these rules :)

    HTH

    Qs
     
    Certifications: MCT, MCSE: Private Cloud, MCSA (2008), MCITP: EA, MCITP: SA, MCSE: 2003, MCSA: 2003, MCITP: EDA7, MCITP: EDST7, MCITP: EST Vista, MCTS: Exh 2010, MCTS:ServerVirt, MCTS: SCCM07 & SCCM2012, MCTS: SCOM07, MCTS: Win7Conf, MCTS: VistaConf, MCDST, MCP, MBCS, HND: Applied IT, ITIL v3: Foundation, CCA
  3. Arroryn

    Arroryn we're all dooooooomed Moderator

    4,015
    193
    209
    I'm doing this at the moment... albeit slowly, amongst my other jobs :biggrin

    I have a template in Word, with basically "Dawn's Config Notes" at the top of the header, and "Put Application Details Here" in bold at the bottom of the header. That's split from the doc with an underline, with the following:

    Application
    Contents
    Body Text

    Then the fonts et al are set. That way I know my documents are going to have a consistent look and feel, no matter what I'm writing about (which is important to me at any rate!)

    Word is honestly just fine for this kind of thing - just remember, Alt Gr is your friend. I came across someone who had been making documentation for years, and had been getting full print screens just to go in and crop down to a pop-up window they wanted. heh heh :)
     
    Certifications: A+, N+, MCDST, 70-410, 70-411
    WIP: Modern Languages BA
  4. Raffaz

    Raffaz Kebab Lover Gold Member

    2,976
    56
    184
    Ive just done something similar at work on ADSL2+. I used word aswell but i put screenshots into the document aswell to make it even simpler :)
     
    Certifications: A+, MCP, MCDST, AutoCAD
    WIP: Rennovating my house
  5. Sparky
    Highly Decorated Member Award 500 Likes Award

    Sparky Zettabyte Poster Moderator

    10,718
    543
    364
    Keep in simple, if you were to write everything down to check a wireless connection it would be 100000 pages long. :biggrin
     
    Certifications: MSc MCSE MCSA:M MCSA:S MCITP:EA MCTS(x5) MS-900 AZ-900 Security+ Network+ A+
    WIP: Microsoft Certs
  6. Big_nath

    Big_nath Kilobyte Poster

    397
    8
    44
    Thanks Guys!

    It is going to be a mammoth task, i'm starting to wish i was never asked.
     
    Certifications: MCP, MCSA, MCSA:M, MCSE, MCTS
    WIP: A few
  7. Sparky
    Highly Decorated Member Award 500 Likes Award

    Sparky Zettabyte Poster Moderator

    10,718
    543
    364
    I know what you mean mate.

    I always find "How to" guides more useful, troubleshooting guides are more hassle to produce and probably wont be used as much.
     
    Certifications: MSc MCSE MCSA:M MCSA:S MCITP:EA MCTS(x5) MS-900 AZ-900 Security+ Network+ A+
    WIP: Microsoft Certs
  8. BosonMichael
    Honorary Member Highly Decorated Member Award 500 Likes Award

    BosonMichael Yottabyte Poster

    19,183
    500
    414
    In my opinion, people are either born with troubleshooting and a logical mind, or they aren't. It's not really something that can be taught. Certainly you can improve your knowledge... but without logic and a scientific method to deal with the unknown, you're not likely to do well.

    How-to guides are great. Troubleshooting... not so much. There are simply too many factors to consider! Certainly you can include the most common scenarios... but beyond that, the tech is gonna have to learn how to fire up the Googletron and figure it out for themselves. Otherwise, they never learn to research on their own.

    My 2c. :)
     
    Certifications: CISSP, MCSE+I, MCSE: Security, MCSE: Messaging, MCDST, MCDBA, MCTS, OCP, CCNP, CCDP, CCNA Security, CCNA Voice, CNE, SCSA, Security+, Linux+, Server+, Network+, A+
    WIP: Just about everything!
  9. soundian

    soundian Gigabyte Poster

    1,460
    71
    107
    I think a "How to..." guide is the best bet too. I'd gather information on the commonest/stupidest avoidable errors as well. This should maximise your results while minimising the amount of guides you have to write.

    I suspect the biggest challenge you face is getting people to remember that there are "How to..." guides.
     
    Certifications: A+, N+,MCDST,MCTS(680), MCP(270, 271, 272), ITILv3F, CCENT
    WIP: Knuckling down at my new job
  10. nugget
    Honorary Member

    nugget Junior toady

    7,796
    71
    224
    A word document is just fine. Add in some screenshots and you're laughing.

    How to docs are just great. You can break anything down into single tasks and write a quick how to doc about it.
     
    Certifications: A+ | Network+ | Security+ | MCP (270,271,272,290,620) | MCDST | MCTS:Vista
    WIP: MCSA, 70-622,680,685
  11. MrNerdy

    MrNerdy Megabyte Poster

    544
    4
    0
    Depends who's going to read it, if it's non techies then keep it simple!
     
    Certifications: ECDL, CiscoIT1 & A+
    WIP: Girlfriend & Network+
  12. VantageIsle

    VantageIsle Kilobyte Poster

    446
    8
    49
    I do this a lot at work, keep it simple, use screen shots and don't explain everything!!

    I always get someone to test it out, print off the instructions and get them to follow it. They will soon let you know if they get stuck.

    Once you have a large collection of these documents they can actuality save you time.
    I support some field engineers who are quite competent, sometimes I can just email a guide to them to fix a problem rather than remote to their pc or talk them through resolving a fault/setting something up.
     
    Certifications: A+, ITIL V3, MCSA, MCITP:EST, CCENT, 70-432-SQL, 70-401 SCCM
    WIP: MCSA upgrade MCITP:SA then EA
  13. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    180
    287
    I agree about considering your audience. Write it for whoever's going to read the thing.

    Think about manuals you've read that you've hated. You probably said to yourself, "I could have done a better job than that". Then write a manual the way that makes sense to you. Chances are you'll at least come close to a good document.
     
    Certifications: A+ and Network+

Share This Page

Loading...
  1. This site uses cookies to help personalise content, tailor your experience and to keep you logged in if you register.
    By continuing to use this site, you are consenting to our use of cookies.