documentation basics

[jeffcapes]

I am doing some research into best practice systems/network administration and wanted some insight from admins who work with VMware technologies (e.g. ESXi, Horizon) in their data centres view on something.

I have been reading some best practice guides which always recommend that teams who manage virtual server environments and supporting hardware should maintain documentation and diagrams to demonstrate the virtualisation architecture and how it interfaces with the overall network environment.

My questions are as follows:

1. Would creation of such documentation typically be a manual exercise or are there automated tools to help document and illustrate the current architecture? If there are useful tools for creating such documentation, can you detail which?
2. Under what circumstances would such accurate documentation be critical. Whilst I don’t work in a support role, I assume the VMware software hopefully comes with detailed reporting and graphics of the setup, so presumably if that is readily available, what are the benefits of maintaining separate ‘stand alone’ documentation of the same information? E.g. when would you turn to manual documentation rather than view the setup in the management apps directly?
3. What kind of documentation for ESXi hypervisors, hosts and corresponding storage is beneficial to you as administrators?
4. Is the maintenance of the documentation a significant undertaking e.g. time consuming, or does it only require occasional review/update?

I would greatly appreciate any input into the above.

[Duncan Epping]

1. For most people this is a manual exercise, there are some tools (powercli based) which can document your settings though. 
2. I feel it is always good to have documentation, yes you can click in the UI what is configured, but that doesn't tell you WHY it was configured in a specific way. It is good to document the what/why so that when issues arise you have a better understanding of why decisions were made. There could be performance reasons, security reasons, availability reasons, budget constraints etc etc. All of these would be important to understand if you want to make changes
3. For me: Design Document is crucial, the what/why/how etc.
4. No, it is not time consuming, but people don't tend to enjoy writing documentation and as such skip/neglect it.

[jeffcapes]

Thanks so much yes the 'why' and reasoning is a very good point, no management application or auto-generated architecture design app can tell you that.