What goes into your documentation



  • Two main questions for the community.

    What do you put into your documentation? Saying everything is a bit unrealistic although that would be the ideal, there has to be a cut off point where you assume most IT people have that base knowledge and thus doesn't need to be recorded

    How do you write your documentation? I mean more along the lines of format, a log, how-to, etc?

    I'm having an issue of what do I write up, I don't think I've really done anything special so it is difficult for me to continue with documentation when everything seems to be fairly (very) straight forward. I generally do all my write ups as how-to's, which makes them easy to work with and easy to pass along to someone who may not have the same technical acumen as I do.



  • It depends on the purpose of the documentation. Are you writing an SOP for the department? Then it needs to be in a how-to format, and explicitly written. Is it noting work you've done on an issue? Then a log format is ideal for that. The question of how to document much be preceded by what is the purpose of said documentation?



  • Documentation should be geared towards someone who is at least an L2 (so no every little step for someone who has no clue) but enough information to get a person that has some clue to where they need to go.

    • all log on information for every machine (if not standardized)

    • List of known recurring issues and basic info on fixes.

    • Depending on how you do ticketing a link to the tickets regarding recurring issues (the ticket should have your notes of how you fixed it).



  • @Minion-Queen said:

    Documentation should be geared towards someone who is at least an L2 (so no every little step for someone who has no clue) but enough information to get a person that has some clue to where they need to go.

    • all log on information for every machine (if not standardized)

    • List of known recurring issues and basic info on fixes.

    • Depending on how you do ticketing a link to the tickets regarding recurring issues (the ticket should have your notes of how you fixed it).

    Again, this depends on the purpose. While I agree that if you are making documentation for the IT department and them exclusively, this is spot on. But if management wants documentation written up that could be followed by an entry-level L1, then it changes the game.



  • Remember this is for a single business and Not an MSP. We operate VERY differently on that level when we have a team of L1-Engineering. In a business you would be hiring someone who has some experience and is hired to work in your environment.



  • @Minion-Queen said:

    Remember this is for a single business and Not an MSP. We operate VERY differently on that level when we have a team of L1-Engineering. In a business you would be hiring someone who has some experience and is hired to work in your environment.

    True. I don't disagree. However, it would still rest on the purpose for the documentation. IT documenting for IT? Go with Danielle's suggestion. Otherwise, you'd have to look at the criteria.



  • @thanksaj said:

    @Minion-Queen said:

    Remember this is for a single business and Not an MSP. We operate VERY differently on that level when we have a team of L1-Engineering. In a business you would be hiring someone who has some experience and is hired to work in your environment.

    True. I don't disagree. However, it would still rest on the purpose for the documentation. IT documenting for IT? Go with Danielle's suggestion. Otherwise, you'd have to look at the criteria.

    For most organizations all IT related documentation will be geared toward IT. You will have some other reports and info for management/employees but that really isn't what I'm referring to. This is more if you were hired to take over someone else's position how in-depth (and meticulous) would you expect the documentation to be?



  • @Minion-Queen said:

    Documentation should be geared towards someone who is at least an L2 (so no every little step for someone who has no clue) but enough information to get a person that has some clue to where they need to go.

    • all log on information for every machine (if not standardized)

    • List of known recurring issues and basic info on fixes.

    • Depending on how you do ticketing a link to the tickets regarding recurring issues (the ticket should have your notes of how you fixed it).

    That is helpful. I tend to write in how-tos because it s easier for me to think that way but I can see where someone at the higher level would prefer a log of what was done where.



  • @coliver said:

    @thanksaj said:

    @Minion-Queen said:

    Remember this is for a single business and Not an MSP. We operate VERY differently on that level when we have a team of L1-Engineering. In a business you would be hiring someone who has some experience and is hired to work in your environment.

    True. I don't disagree. However, it would still rest on the purpose for the documentation. IT documenting for IT? Go with Danielle's suggestion. Otherwise, you'd have to look at the criteria.

    For most organizations all IT related documentation will be geared toward IT. You will have some other reports and info for management/employees but that really isn't what I'm referring to. This is more if you were hired to take over someone else's position how in-depth (and meticulous) would you expect the documentation to be?

    In that case, I agree with Danielle. Unless it's something to do with proprietary software or some weird issue you deal with on your network that isn't normal, L2 and up. Assume someone can figure out or just know the L1 stuff.



  • @coliver said:

    Two main questions for the community.

    What do you put into your documentation? Saying everything is a bit unrealistic although that would be the ideal, there has to be a cut off point where you assume most IT people have that base knowledge and thus doesn't need to be recorded

    How do you write your documentation? I mean more along the lines of format, a log, how-to, etc?

    I'm having an issue of what do I write up, I don't think I've really done anything special so it is difficult for me to continue with documentation when everything seems to be fairly (very) straight forward. I generally do all my write ups as how-to's, which makes them easy to work with and easy to pass along to someone who may not have the same technical acumen as I do.

    Three things that are vital: Words, Pictures and Arrows.
    Hopefully all three relate to what you are supposed to be writing about. 😃



  • @nadnerB said:

    How do you write your documentation? I mean more along the lines of format, a log, how-to, etc?

    I'm having an issue of what do I write up, I don't think I've really done anything special so it is difficult for me to continue with documentation when everything seems to be fairly (very) straight forward. I generally do all my write ups as how-to's, which makes them easy to work with and easy to pass along to someone who may not have the same technical acumen as I do.

    Three things that are vital: Words, Pictures and Arrows.
    Hopefully all three relate to what you are supposed to be writing about. 😃

    hahaha @nadnerB Sir, That's what i did before 🙂



  • Anyone use video instead of documentation? I thought about doing it, and even got a microphone to use. So if I'm doing a task that I want to document, I just record it as I do it. Then if someone wants to do that task in the future, they can watch me doing it. At the moment, I'm a little self-concious talking into the microphone.

    For written documentation, I find the Windows Snipping tool to be brilliant. I snip bits of my screen into a Word doc. I love the highlighter pen feature of Snipping tool.

    For users a lot of the time now I'll tell them I'll send them instructions on how to do something, rather than telling them how to do it over the phone or showing them in person. Then I'll document it (with pictures) and e-mail it to them. That way, if another user has the same question (or the same user has forgotten what I already told them), I can just forward the e-mail to them. Over time I've built up quite a decent library of user instructions this way, which I need to get around to putting onto Sharepoint for users to self-serve.



  • @Carnival-Boy said:

    Anyone use video instead of documentation? I thought about doing it, and even got a microphone to use. So if I'm doing a task that I want to document, I just record it as I do it. Then if someone wants to do that task in the future, they can watch me doing it. At the moment, I'm a little self-concious talking into the microphone.

    For written documentation, I find the Windows Snipping tool to be brilliant. I snip bits of my screen into a Word doc. I love the highlighter pen feature of Snipping tool.

    Love the Windows Snipping tool, I've actually started using an FOSS utility called Greenshot to grab a lot of my screenshots. Just feels a lot more precise then the snipping tool.

    For users a lot of the time now I'll tell them I'll send them instructions on how to do something, rather than telling them how to do it over the phone or showing them in person. Then I'll document it (with pictures) and e-mail it to them. That way, if another user has the same question (or the same user has forgotten what I already told them), I can just forward the e-mail to them. Over time I've built up quite a decent library of user instructions this way, which I need to get around to putting onto Sharepoint for users to self-serve.

    This is a great idea, I should really start doing this.



  • @coliver said:

    @Carnival-Boy said:

    Anyone use video instead of documentation? I thought about doing it, and even got a microphone to use. So if I'm doing a task that I want to document, I just record it as I do it. Then if someone wants to do that task in the future, they can watch me doing it. At the moment, I'm a little self-concious talking into the microphone.

    For written documentation, I find the Windows Snipping tool to be brilliant. I snip bits of my screen into a Word doc. I love the highlighter pen feature of Snipping tool.

    Love the Windows Snipping tool, I've actually started using an FOSS utility called Greenshot to grab a lot of my screenshots. Just feels a lot more precise then the snipping tool.

    For users a lot of the time now I'll tell them I'll send them instructions on how to do something, rather than telling them how to do it over the phone or showing them in person. Then I'll document it (with pictures) and e-mail it to them. That way, if another user has the same question (or the same user has forgotten what I already told them), I can just forward the e-mail to them. Over time I've built up quite a decent library of user instructions this way, which I need to get around to putting onto Sharepoint for users to self-serve.

    This is a great idea, I should really start doing this.

    Greenshot is AWESOME! I heard about it at my last job and tried it out. OMG! LOVE IT!



  • Installing Greenshot now on my PC at the new job!



  • I use Awesome screenshot : capture & annotate for Google Chrome browser and the snipping tool.



  • @technobabble said:

    I use Awesome screenshot : capture & annotate for Google Chrome browser and the snipping tool.

    Never heard of that, I will look into it now.



  • @technobabble said:

    I use Awesome screenshot : capture & annotate for Google Chrome browser and the snipping tool.

    Sounds cool.



  • The next question I have is, who reviews your documentation? Do you send it your boss for review? Or just put it in [place] and assume it will be good when the time comes? I use the latter simply because we don't have any SOP for documentation here.



  • Here since I am also the person that can get stuck working on something that I haven't seen before I do the review. I would just go through it step by step next time you have to do that item and make sure your documentation makes sense and you didn't miss anything.



  • @coliver said:

    Two main questions for the community.

    What do you put into your documentation? Saying everything is a bit unrealistic although that would be the ideal, there has to be a cut off point where you assume most IT people have that base knowledge and thus doesn't need to be recorded

    How do you write your documentation? I mean more along the lines of format, a log, how-to, etc?

    I'm having an issue of what do I write up, I don't think I've really done anything special so it is difficult for me to continue with documentation when everything seems to be fairly (very) straight forward. I generally do all my write ups as how-to's, which makes them easy to work with and easy to pass along to someone who may not have the same technical acumen as I do.

    I keep a standard format and try not to re-document anything that can easily be found online. My documentation is pretty much an explanation of why I did things the way they are, with config info, logical maps, basic info that should help any IT pro that is around after I leave can look at and be up to speed fairly quickly. I review it quarterly too, make changes and updates as needed.


Log in to reply