Microsoft Doesn’t "Get" Documentation (In Other News, Water is Wet)

Tags: Corporate Stupidity, Documentation, Windows Server, RIS, WDS

I don’t mean to say that TechNet and MSDN are bad – quite the opposite in fact. I don’t know that I’ve ever seen such a huge repository of documentation. But what always appears to be missing is the “overview” or “tie it all together” document, required so that the student knows what he doesn’t know.

Here’s a case in point from the Windows 2000 beta, and likely Windows 2003 as well – by the time Windows 2003 came around I already had the knowledge so I wasn’t hunting for it.

What’s the first step in getting the Remote Installation Service going?

Veteran users of RIS from Windows 2000 and Windows 2003 will know that the answer is simple – RISetup.exe on the server. But where was that documented? All the “Quick Start” type guides spoke of having the Windows media and your applications being MSIs, then (paraphrasing), “set up your RIS Server and add the images to it”. No mention of RISetup.exe or RIPrep.exe to be found. No documentation on the SIF files, their locations etc. Nothing on post-RIPrep customisation, or what you could and couldn’t do while the image was still on the server.

Nor was there guidance on sizing, performance, deployment, multiple site deployments etc – it seemed that it was expected that every admin and consultant would just “work it out”.

The latest item in this vein, funnily enough, is Windows Deployment Services – the replacement for RIS. Well not WDS, specifically, but the Microsoft Deployment Toolkit or MDT. MDT is built on top of WDS, and is for creating hardware-independent images and being able to deploy device drivers, applications, patches and customisations on top of a standard Windows image – so you can plaster Vista across your network in no time flat.

Except that once again, despite thousands of pages of documentation, the initial “here’s how you get a basic one going” is spread across the entirety of the MDT documentation pack. You have to know which of the MDT documents (there are about 25) contains the information you want, and it’s not the planning guide or the Getting Started guide.

No, critical information about the Distribution$ share (wait, how do I even know about this share?) is in the helpful documents, “Workbench Imaging Guide” and “Image Engineering”. But you also need the documents, “Infrastructure Remediation Feature Team Guide” and “Preparing for LTI Tools”.

Infrastructure Remediation Feature Team Guide? Are you kidding me!? I’m deploying a new SOE not building a new data centre!

Here’s what I think a “Getting Started” guide should look like for MDT, remembering that this is targeted at the administrator who has never seen MDT before:

  1. Install Windows Deployment Services. Links here to separate documents, one each describing a vanilla install of WDS on a supported OS– i.e. add the role for Windows 2008, or install SP2 for Windows 2003 and then add the Windows Component.
  2. Create this hierarchy (Distribution$) on your server and share it. Use this tool and this wizard.
  3. Install the AIK and MDT (with links to the downloads). Maybe even make it an unattended install so the right components are installed!
  4. Use this wizard to put a copy of a client OS on the server (two links – one for Vista/2008 and the other for XP/2003).
  5. Use this wizard to put an MSI application on the server (Browse to any MSI, Add to the “image”)
  6. Use this wizard to add a new driver to MDT (Browse to the .INF files)
  7. Here’s how you create a Capture Image. (Use this tool and this tool and this tool.)
  8. Here’s how to capture the PC using the capture image.
  9. Here’s how to deploy the simple image.

Each step should have links into the documentation hierarchy. But no admin I know has the time to read 2000 pages of documentation so he can roll out a new desktop.

The quick list above is probably 75% of the process for most administrators. Each step can describe the tools being used – what the shortcut name is for a GUI tool, or the executable name for a command line tool. After all, how many administrators still don’t know about PEIMG and ImageX?

Also MIA in the documentation are the answers to all the initial “WTF”-type questions. What’s a task sequence? Why and when would I create a new one? What are the phases of installation? How do I know what piece goes where (e.g. application deployment – Post Install or Restore State)?

Where’s the document that shows how things get used (rather than documents describing what a folder is for)? Or that says, “Here’s an example of a really good way to start with this hierarchy of new folders”?

And my biggest annoyance (MDT specific this one) is that the MDT documentation seems to assume a team of 30 or 40 people – dozens of pages in the MDT documentation set deal with the need for more than half a dozen different teams, all with their own roles and responsibilities. For example, the “Stablilizing Phase” has the following management roles (ignoring actual, you know, workers), which all seem to be assumed to be separate people:

  • Release Manager
  • Change Owner
  • Training Coordinator
  • Communications Coordinator
  • Documentation Coordinator
  • Testing Coordinator

Sure it’s nice to have that for the dozen companies with that many spare and underutilized IT staff, but we’re not all deploying 100,000 machines and we don’t have time to figure out all the connecting bits ourselves.

No Comments