Site Documentation

anything I don't mind

anything I don't mind

anything I don't mind

Permabanned
Joined
28 Dec 2009
Posts
13,052
Location
london
What documentation do you write if any for the systems that you control? To what extent do you write documentation. I was thinking about usefulness documenting certain system properties. I just thought what is the point. So i was wondering if you document everything about your systems? At some point for example documenting vmware datastores and network storage and vmware network interfaces. What more can you do than take a screenshot of the network configuration page? its self explanatory. It seems pointless to document that because someone could just see it by looking at it. What purpose would documenting it have?
 
We document everything

The idea for us is that if anything where to happen to me/colleague then someone else could walk in tomorrow and still be able to manage and maintain key business systems until someone else can be brought in.
 
Yes i understand that part. But what I am trying to say is that documentation should not realy be needed for that sort of thing. If someone is meant to know vmware and storage and windows server and so on. as long as they have a server list with ips and passwords, they should be able to work the rest out themselves. How can having the network interfaces of vmware in a word document help someone new to the site? he can just login and look at the network configuration?

So the question was kind of more on the side of, where is the line between information that a new guy could use and being OTT with the documentation.
 
Well for example if your VM host went down tomorrow where's your reference to tell you what IP addresses it used to talk to the SAN?
 
Some things are worth documenting for sure. It's possible to go a bit overboard though but if you think it could be useful for later then it's probably worth documenting somewhere.
 
In my opinion documentation on obscure and bespoke systems is priceless but mainstream products, such as your vmware example don't need documentation as such, rather just a quick to reach inventory of where the components are is all you need if the **** hits the fan.
 
I disagree - everything that can be documented should be. I'm not saying go into details like how the cables are tied to the rack, but you need to know what NIC ports go to which switch ports (in the VM hosts example), what VLANS are tagged onto those ports, what the IP addresses in your infrastructure are etc., this is as well as configuration backups of switches, routers etc.

Saying that it's obvious once you're in the vSphere Client isn't helpful if your environment has fallen over. Likewise, documentation is a great source of information and the idea is that it's more readable than trawling through config files.

At the least you should have a list of servers (virtual or physical) and an idea of what OS it runs, what its function is, what other servers it needs to talk to etc. Finding out that one seemingly standard box was also the RADIUS server for your WLAN after you've deleted it doesn't help.

Same goes for things on your network that you've set static leases on, you could trawl through the DHCP server to get their MAC addresses, but it's a lot easier to have it in the documentation.
 
Last edited:
I agree with Caged, you should document as much as possible as you never know what might happen in a DR situation, or even at 2am when something has gone down and needs to be brought back up.

Not only should the configuration be documented but also how to access the systems should be documented and maintained, (again for when it's 2am and you are dialled in remotely and need the ILO ip address for a server hundreds of miles away).

An important bit of documentation which is often missed is the data flows and interdependencies between different systems ... You need to take an extended outage on system A ... what other systems interface and rely on this system? Are there application dependencies which mean that if the application on system A is restarted then that on system B must be too?

One thing you can do is have standard build documentation and then the server documents are basically follow that and then this is the configuration added (extra packages, settings etc). We do this so whilst our stand RHEL 6 build document is ~100 pages (including appendices, most of it is to do with security hardening 90% of which is automated with the script/kickstart provided with the document but we need to provide the manual steps too) the individual server docs may be only a couple of pages.

The best company I worked with had a full documentation stack plus copied DR info from every server to several offsite locations. As such we were confident that even there biggest, most complex systems, could be rebuilt from scratch and backups in a minimal time frame at a DR site with minimal issues and this was proved through testing.

Put it this way ... It's 3am and the building containing your environment just burnt down taking your VMWare hosts and vCentre server with it. It had critical systems on it and you need it rebuilt now (maybe the Boss should have paid for SRM, to late now, and you did remember to store a copy of your docs offsite didn't you). What was the networking and storage setup across the environment (including vlans)? What was the configurations of the VMs? ... oh and the Oracle RAC cluster which was in the next rack .... You need to rebuild that and recover it's data too ....
 
Well some people agreed with my point and other people as i would suspect see the need to document everything. I understand having documentation and I have no problem with that. But the way i look at it the network interfaces of the vmware is not something that needs to be documented, you can just work out from what is already there what you need.

If the building burnt down we would invoke DR which has a completely different environment than the in house esxi and even then if you had that documentation it would not help in a dr situation because the storage is different. If you had to rebuild the entire system from backup tapes and brand new hardware. It would not necessarily have to have the same ip addresses to contact the storage. It would only be important that the storage is presented to the esxi. But in the unlikely event of that occurring it would help to have everything documented.

But for example group policy, it was said that they want to know what group policy is in use and why. I thought this was pointless because if someone does not know how to interpret group policy just by looking at it then i don't think they should be touching it in the first place. ie if you need documentation to help interpret gpo then you don't know gpo. IF they want to keep a backup of gpo that is something different, its already backed up in to the several dc backups we have. Could even do a manual gpo backup and attach it to the docs.
 
Last edited:
That's not the point though - it's possible to work out that a certain GPO is making changes to certain keys in the registry and have no idea why it's doing it - it could be a legacy piece of software needs permissions changing on keys to run in a limited user account, but documentation would clear that right up. All you need is to use the comment field that each GPO has to write a couple of sentences about what it does and why.

I haven't seen a good argument for not doing documentation, if you're doing it right then it shouldn't take you very long at all, and it serves as a useful check because you're forced to think about why you did something a certain way while you're writing it.

You're right that you wouldn't have to set everything up the same if you were rebuilding from scratch, but having the paperwork that you can look at after 18 hours rebuilding an environment is a lot better than having to think about it.
 
I agree with Caged, We document everything on how it was built. In the event of total failure I want to know how it was built. I don't want to guess any of it.
 
I totally agree with you. If you know how it was built, AKA how it works, then theoretically you would know how to solve any issues.

What to do's only give you a quick solution, not really knowing what you did was for. This is based on my experience, so please don't flame me.
 
Some people go OTT with docs, they have pages of why a certain system is setup the way it is, almost like a project management doc. In reality you just need visio's, IP tables and dataflow diagrams - you don't need all that other stuff that many `contract` staff waist time putting into a doc.

There's an art to writing decent technical docs, not many people have it. They either waffle too much (like above) or just produce a doc full of screenshots.
 
Rubbish, knowing why a system has been setup in a certain way can be very important as if you only have "visio's, IP tables and dataflow diagrams" then how are you going to know if you make any changes to the system it will not break something which had a reason why it was configured that way in the first place? Also remember that for non-Windows OSes there are frequently many different ways of doing the same thing so having a documented agreed standard means that builds are consistent which makes support easier.

Yes, documents should not contain lots of waffle (and I have seen many that have), but it is very much valid to have server documentation on how systems are configured which may well include short notes on why things were done for important points.
 
Specific config is held in chef cookbooks which are versioned in git. High level architectural stuff obviously gets documented.
 
Documentation should contain specific configuration information (specific for environment and any other best practice information) plus steps on how to configure said items up comprising specific orders of completing tasks (which save time) and clarity to ensure the configuration is done correctly to company standards/best practice.

And it shouldn't be an IT howto, it should be clear for a competent IT person to review and implement easily.
 
Last edited:
You must log in or register to reply here.
Back
Top Bottom