1

My background is in programming. I know what is needed to document for my code. I do not know what is needed and should be documented for our network/servers etc.

I saw many threads ab out this but more or less about what they’re using, how they’re storing the information etc.

I am looking to add documentation for everything in my shop. We recently had to setup a new server, in a hurry, as the other died. Everything was setup successfully, except for one share. This was resolved but showed my immediate need for documentation.

What are the best practice for this? Any help is is greath appreciated.

Hmm, no best practice option for me under the groups.

18 Spice ups
2

I’ve found that the best way to approach this (not that I always follow this rule), is approach a system like it is your first time working with/setting up/repairing it, and then document the things that are needed for each of those tasks.

Documentation is a significant part of what we do, but it is one of the most difficult things to maintain especially in smaller shops.

One of the things that we’ve taken to doing lately is adding to the tickets we close whatever steps we took to solve a given issue so that the helpdesk is a knowledge base for us.

5 Spice ups
3

In addition to Sosipater, I use the logic: “If I was fired tomorrow, what would someone need to know to work with everything”

Document:

Setup, Special Configurations, Any known issues, Why you set things up a certain way, what is affected when you restart certain servers (this is big because we had an undocumented database that went down during a restart of a server that seemed to have nothing installed). If you even have a remote thought that it should be written down somewhere, DO IT.

6 Spice ups
4

Don’t forget that good place to build up documentation is within your own ticketing system. Many will allow for the construction of Visio Diagrams, or the cross referencing of documents and etc.

1 Spice up
5

One way to look at documentation and just how critical it is is disaster recovery. If everything were destroyed, what information would you need to have someone completely unfamiliar with your system come in and set it up with you. You need to have a complete inventory, including vendors of your equipment, configurations and the reasons why it is configured that way for future refrence, user names and passwords, and so much more we could spend days on it.

6

rmuniz9336 wrote:

Don’t forget that good place to build up documentation is within your own ticketing system. Many will allow for the construction of Visio Diagrams, or the cross referencing of documents and etc.

Currently we only use SW, well I should say I as I’m the only user on it (for now).

1 Spice up
7

Check out NetworkDNA for good templates.

http://networkdna.network-documentation.com

8

Elgin;

I subscribe to RunBooks as a great methodology for documenting “everything” about a system, and it’s quirks, etc. You can find out more about RunBooks, RunBook Automation and other ideas for that by first reading this wiki article .

Next I would suggest that you use the SYDI project to begin to document your hardware (servers, desktops, etc). This is a documentation package that must be used with Word, as that is how the scripts are built, but that provides great amounts of information directly into word using the scripts. You can find the SYDI project home page here .

I highly recommend SYDI for the depth of data it provides and the speed with which you can begin your documentation projhect. I have used it in every environment from a single server and a few workstations, through large phyiscal server installations and multi-million dollar VMware installations with 20 hosts and >100 guest servers and workstations.

You can also script it (since it is just a script itself) so that you can update changes to the original document everytime you make a change to the hardware under review. Think monthly MS updates, etc.

These should all become a part of your DR documentation, both physical and electronic, copies should be onsite for your tech team to review as needed too.

SYDI gives you the power to quickly document your network. RunBook methodologies give you a course to follow to present that data. You can leverage that into DR documentation, replacement schedules, and so on.

Hope that I have been of some help to you.

Yours sincerely

Andrew Martin

30 Years in IT (January 3 1982 - today)

And I would have gotten less for murder

2 Spice ups
9

My theory with documentation is someone with a very basic understanding of the field/technology needs to be able to pick up a document, follow it, and achieve the complex and difficult results an expert in the field would achieve (random variables aside).

They need to be detailed, and the detail needs to be exceptionally heavy where the component/aspect is either critical to operation/success, or particularly complex.

10

iandrewmartin wrote:

Next I would suggest that you use the SYDI project to begin to document your hardware (servers, desktops, etc). This is a documentation package that must be used with Word, as that is how the scripts are built, but that provides great amounts of information directly into word using the scripts. You can find the SYDI project home page here .

That’s not the first time I’ve seen the SYDI project mentioned. Is it still being actively developed? The web site’s last update as 3 years ago. How does it handle things like Win2008R2 or vSphere 5?

11

@iandrewmartin - in the military the ‘run books’ used by everyone (including IT) to do their daily jobs and recover systems are called ‘battle books’. Turns out that people are more likely to use/update the documented steps in the books if they have a cooler name. Most IT professionals are male, and calling something a ‘battle book’ instead of a ‘run book’ gets the team to use it more diligently.

12

Boom! Superhero books! :slight_smile:

13

The critical information you need to capture are those configurations and settings that are unique to a device or system, anything that makes it different then clicking next, next, next, finish during setup. Specifically you want to get down what it would take to recover the system for next time. ( I know, you just learned that lesson when you rebuilt that server ).

Best practice guidelines for this process are available via any of the frameworks - COBIT, ITIL, ISO 270001. Microsoft Operations Framework.

For a quick documenation project I’d start by diagramming out the infrastructure (firewall, routers, switches, wiring, ups, servers, printers, etc) as it often has the fewest changes over time and will give you the greatest understanding of how the overall architecture has been assembled.

Next I’d map out where the services and applications are located. In this context a ‘service’ is something offered by the IT infrastructure to the organization, anything from that broken share you mentioned through the website, email, the accounting system, etc. Management could care less where DNS comes from, but when it’s broken you need to know where it was and how to get it back.

At some point you’ll be able to add details to the diagrams that aren’t necessary to rebuild the system, but help in operations overall - serial numbers of servers, warranty expiration dates, OS versions (and where the licensing came from), disk space, RAM, video specs… Spiceworks can give you a lot of this information.

You should centralize the documenation if possible, and try to get everyone to help you if you can. Use a revisioning system in the document name (v 1.2.3.4.a) and create a structure so that you can find that specific detail when you need it.

Eventually you’ll be able to take the information you’ve generated and the processes and procedures you follow and combine them into ‘Battle Books’ - or ‘Run Books’ as iandrewmartin called them.

14

I have changed this to a discussion, as I see lots of valid points and information. Thank you everyone for you input. This will help me greatly to get this placed documented.

15

Documentation. My pet subject.

I note with interest how many people think that network diagrams and workstation inventories are very important to document. Not us here. Network diagrams collect dust too quickly. Workstation inventories can never be trusted to be up to date. These things are great for impressing mangers but I have never made much long term use of them. If I need a workstation inventory I use a tool like Spiceworks to get me an up to the minute report of what is out there and what’s in it. A network diagram is only useful if it has a complete list of all WAN circuits IDs and Telco account numbers behind it.

My suggestions for documentation…

  1. Use it. It needs to be used daily. Read daily, maintained frequently. If you are not using it then people will forget it exists and it will gather moss.

  2. Access. Everyone in the IT department needs to know exactly where to find it. It should have some security around it to control who has access to what, but not so tight that people feel they are not part of the team. You need them to know that they are expected to keep it up to date.

  3. Discipline. Beat the staff up if it is not getting kept up to date. If they are on holidays and the documentation is wrong, call them and get them off the beach to fix it. If they are in hospital, send a taxi to get them. No leave without it being up to date. I have a check box on our leave application form that they need to tick and sign off saying that their documentation will be up to date before they go on leave.

  4. Pass it around. We have DR procedures for our major clients who pay for us to do DR testing. This testing procedure is carried out by an engineer that was not involved in writing the procedure. This makes sure that it is tested properly. When staff go on leave other engineers are expected to be able to have all the information they need to maintain our client sites.

  5. Audience. You don’t need a procedure to renew a Web Security Certificate that an idiot can follow, because you are not going to employ an idiot to do it. That would be idiotic. You just need the basic details laid out clearly in the place that everyone would expect to find it so that your qualified IT support people can get the job done. Things change too fast in IT for you to spell out a step by step procedure for everything that needs to be done. That’s why you pay for people who can ‘wing it’, learn fast. For the rest, there is google.

  6. What to document? Document this:
    • Where do I find the tool to manage that that thing?
    • What is the password?
    • Who do I call if it is busted?
    • What information (serial number, circuit ID, Agreement number) do I need to tell them to get the action I need?
    • Where can I find more information?
    • When does it expire?

  7. Keep the rest of it in your face, make it obvious. Use labels profusely. I put labels on the servers with the maintenance agreement number and expiry date on it. Put descriptions in Active Directory objects and other management tools so that you can see what a machine if for and so you can see when a user left the company etc. It is always better to have the information staring you in the face than having to go off and get it.

End of rant.

1 Spice up
16

In reply to Svend - Excelan in 100% agreement!

I have found with people trying to covet the inner workings, they normally are a person in a higher position and/or management over the network ect…

So this is only going to go so far tragically, for the ones who take credit for everything and shockingly NEVER make a mistake!

The games people play and politics seem to be worse in the Tech arena…

They should have an reward for Brownie of the week, I am not kidding.

17

Svend - Excelan wrote:

Documentation. My pet subject.

  1. Use it.

  2. Access.

  3. Discipline.Z

  4. Pass it around.

  5. Audience.

  6. What to document? Document this:
    • Where do I find the tool to manage that that thing?
    • What is the password?
    • Who do I call if it is busted?
    • What information (serial number, circuit ID, Agreement number) do I need to tell them to get the action I need?
    • Where can I find more information?
    • When does it expire?

  7. Make it obvious.

Awesome!

18

Ditto

19

It does depend a lot on the workplace, the IT environment, and the likely audience and their technical understanding.

I’ve found one way to document the procedure for setting up something new is to write down absolutely everything I can think of, step by step, and then give it to a colleage to see if they can get from A to B. If they can’t, I make a note of where they got derailed, rewrite that part, and try again. Especially in smaller, ad-hoc shops, there’s always the chance that someone installed something five years and three IT guys ago, it just broke down, and there is no documentation whatsoever. I’d like to think that if I install something, than in five years from now it won’t matter what I’m doing because my replacement will be able to read my notes on it and at least have the basics of an idea of what was going on at the time.

20

Svend makes some good points - I FIRMLY agree that it needs to be a living document used by the team each and every day. That’s probably the biggest takeaway from this entire discussion, you need to use it!

I guess it’s my risk and infrastructure backgrounds that place emphasis on getting the infrastructure diagram down first. I’ve found it gives a great overview on the system, you wouldn’t believe how many bad designs I’ve found that way with easily corrected issues - we just needed the big map to make it visible.

It also makes it easier when the auditors come by. Show them the map, the vulnerable points, and your layers of defense. Still, if you can use tools that make mapping automatic (um, like Spiceworks) it’s very helpful in keeping the information up to date.

@stevinator - we always assigned the routine documentation (new user set up and system build) to whomever was new to the team with the instructions “It’s all in there”. They’d come back with whatever wasn’t ‘all in there’ and we’d have them add it to the document for the group to review. It helps to keep everything current, and gets them some documentation skills.