Installation documentation

Question

I'm looking for a good template on server-side installation of software for a project I'm working on.

The client-side is pretty straight-forward. The server-side installation is a little trickier. It is made up of several pieces (services, database connections, dependencies, ports that need to be unblocked etc) During a recent test, several undocumented pieces were discovered. Now I need to create installation guides for our disaster-recovery plans and ways to test the installation without necessarily having a "full-up" system to test on.

I'd really like a suggestion of where I can get a template or a really good example of such a document. I'd like it to be something that an operator could read and comprehend in the heat of a recovery.

---

[EDIT] Our current documentation comes mainly from the questions our administrators have had during off-site tests. As new code is written, I'd like to make sure the documentation is written ahead of time. I've been collecting VMWare images to start testing, but was looking for some good examples. It's a Windows Server shop (2000 & 2003). Word templates would be great, but if I could see good documentation, I could create the templates. Any suggestions about what should be tested would be great as well.

---

[2nd EDIT] I've gotten several good ideas from the answers posted. After changing my Google search, I came up with some good starting points. They're not perfect, but they are a good start.

Microsoft Exchange - http://technet.microsoft.com/en-us/library/bb125074(EXCHG.65).aspx iPhone - http://manuals.info.apple.com/en_US/Enterprise_Deployment_Guide.pdf

http://www.novell.com/documentation/gwgateways/gw7_exch/index.html?page=/documentation/gwgateways/gw7_exch/data/ab32nt1.html http://cregan.wordpress.com/2006/06/22/exchange-2003-step-by-step-installation-instructions/

http://technet.microsoft.com/en-us/magazine/cc160942.aspx

Covers planning in the design stage well - http://www.onlamp.com/pub/a/onlamp/2004/04/08/disaster_recovery.html?page=2

---

[Edit 10/29/2008]
THIS is the type sample I was looking for. It doesn't have a lot of garbage, but seems to explain enough of the why along with the how http://wiki.alfresco.com/wiki/Installing_Labs_3_Nile

Answer 1

The most complete method that we've come up with for creating our DR documentation, involves going through a full cycle (or two) of installation, and documenting each step along the way.

I realize this can be a bit difficult if you don't have a test (or replacement) system to use to create your documentation - but it's worth lobbying for running through this cycle at least once.

(I recommend twice, the second being done by someone not involved with the project - this is how you test the documentation for future admins, who may not be as experienced with the process.)

A side effect of the above is that your documentation grows fairly large - last I had to do it, I believe the completed installation manual for our database servers was 30+ pages.

Answer 2

This is kind of too vague to answer. What's the server platform?

What operating system? What kind of server are we talking about (web server? db server? application server?)

It depends on so many factors. Need more info...

Answer 3

Depending on the admins, automation is helpful. I've had windows admins that want a Word doc with step by step instructions and other admins that wanted a script.

However, some helpful things to include, probably as sections

• Database changes
  • Scripts to run
  • Verification that they worked
• Configuration changes
  • what are the change
  • where is a version of the new file (In my case they diffed the two, which helped reduced errors concerning production-specific values)
• General verification
  • what should be different from the user perspective (feature changes)
• For web farm deployments, it might be helpful to have a coordination document concerning how the servers need to be pulled in and out of pool.

Answer 4

What should be tested? Well, in the case of a web site, "can you get to the page?" Include a URL as a starting point and let the admin click through to a certain point. It is not necessary for the admin to go through the whole QA cycle, just a confirmation that what you meant to be deployed is really what got deployed.

---

Other ideas Also, we (my team at my last job) had QA test the deployment. As a QA person should be, he was not intimate with the details and as he deployed to QA, we were able to get feedback on what went wrong.

Another thing that is useful is sitting down with the admin(s) before the deployment. Go over the instructions and make sure they understand them the same way you do.

---

Template? Just make sections that have fields for data such as URL to DEV, QA, and PROD. When you write out the instruction you can refer to those. Just make it clear what is being deployed.