How to create top notch VCDX application documents

I don’t presume our VCDX application documents were perfect, far from it. We had holes in our design that kept me up at night, but we had pretty good damn documentation which is even more important when you write a fictitious design but not only of course.

The main thing to remember when you write the design is write it as if the IT manager of the customer is supposed to read it, there is a big chance that his technical knowledge is off 🙂 and he is very worried about the business requirements being achieved. He will probably give the documents to his technical staff for review as well and they will love punching holes in it.

Here are a few tips:

1. Don’t copy from the templates – I know many are using the vSphere services kit as a template for the VCDX application, but if you want to have top notch documentation don’t copy off of it, write your own verbiage. You can draw inspiration from it, maybe take the document structure for help but if you write your own design with your own explanations it will have an impact.

2. Explain explain explain – What ever design decision you write try to put an explaination and reasoning next to it, for example

This will eliminate a lot of the questions the reader has while reading, and hey, you need to have the reasoning anyway for the defense, so do it in the doc.

3. Weave in the business requirements and constraints throughout the documentation, one of the main goals of the VCDX is not technical but the ability to understand the customers business  requirements and translate them into the architecture and operations, this is very important for the documentation but also for the defense presentation (which I will have a separate post for). One thing you can do is put the business requirements that alluded to your decisions in the beginning of every chapter.

4. Spend as much energy on the other documents as you put on the main architectural design. In addition to the main document you need to have the following:

• Implementation plan – I used MS project to create a Gantt and then exported to PDF. Don’t miss a step and add reasonable timing and responsibilities to each task. Remember to have kick off tasks like intro meetings and interviews with stakeholders and closure tasks like training etc.
• Installation guide – A lot of screen shots, this is the time where you can go ahead and install your proposed solution in the lab. During installation take every possible screenshot and put it in your Installation guide with explanations. This is also where working in a team helps a lot, you can divide the tasks between you.
• Verification tests – This is where you put all the decisions you make in your design to the test, of course you can’t have all of them, its almost impossible in my mind to have everything tested but try to cover as much as you can, this is a very valid question to get in your defense: “how did you make sure your decision and assumptions are correct?” answer should be “I put a test for it in the verification tests document”
• Operational guide – This is the customer’s day 2 operations. If you have in the design anything that suggests an operation the customer should know about put it in this document. If you can do it with screenshots the better.

5. Write your own unique chapters – These can be things other people haven’t put in their design due to relevancy, this will also give your design your own personal flare. I like to write chapters that I think any customer reading it would like to have, examples could be: Risk mitigation chapter, Budget spending chapter, Business critical apps focused chapter and anything that is relevant to the design from the customer’s perspective. The more you try to think like the customer reading it  you have a better design.

6. It’s not the quantity of pages that make your design good, it’s the quality. What do I mean by that fortune cookie sentence? Don’t put unnecessary information in the design, the panel (your customer) has enough to read.

7. Don’t skimp on diagrams, put diagrams where ever they are needed, this will help you later in preparation to the defense, you will just copy paste to your presentation and here you saved on a lot of effort for later. It also makes your documentation look more interesting.

8. Grammar and visibility of the documents are very important, make sure that if you are not a native English speaker that someone looks at your docs for grammar issues. For example all references in our design to VMs was written as “VM’s”, thanks to a good friend of mine that corrected me on it we fixed it with “replace all”. Also make sure all fonts are unified and that the documents have the same look and feel. Good advice for any architect writing a customer facing document.

9. Check your references – If you add references to different chapters in your document or between documents make sure they are all valid before submitting. Making them as hyperlinks adds a nice touch as well and makes it easier for the reader to move in the document.

To conclude, write your own documentation, make sure it looks good and has exactly the right amount of information, goes without saying that you need to make sure the blueprint areas are all covered . Most importantly sit down and just write until your knuckles become sore.

Niran

here are links to other VCDX articles i wrote:

To VCDX with a fictitious design – Part 1 – Our VCDX Journey

To VCDX with a fictitious design – Part 2 – some lessons learned

Handling sub-optimal design decisions before the VCDX defense