(For more resources related to this topic, see here.)

The design documentation provides written documentation of the design factors and the choices the architect has made in the design to satisfy the business and technical requirements.

The design documentation also aids in the implementation of the design. In many cases where the design architect is not responsible for the implementation, the design documents ensure the successful implementation of the design by the implementation engineer.

Once you have created the documentation for a few designs, you will be able to develop standard processes and templates to aid in the creation of design documentation.

Documentation can vary from project to project. Many consulting companies and resellers have standard documentation templates that they use when designing solutions. A properly documented design should include the following information:

• Architecture design
• Implementation plan
• Installation guide
• Validation test plan
• Operational procedures

This information can be included in a single document or separated into different documents.

VMware provides Service Delivery Kits to VMware partners. These kits can be found on the VMware Partner University portal at http://www.vmware.com/go/partneruniversity, which provides documentation templates that can be used as a foundation for creating design documents. If you do not have access to these templates, example outlines are provided in this article to assist you in developing your own design documentation templates.

The final steps of the design process include gaining customer approval to begin implementation of the design and the implementation of the design.

Creating the architecture design document

The architecture design document is a technical document describing the components and specifications required to support the solution and ensure that the specific business and technical requirements of the design are satisfied.

An excellent example of an architecture design document is the Cloud Infrastructure Architecture Case Study White Paper article that can be found at http://www.vmware.com/files/pdf/techpaper/cloud-infrastructure-achitecture-case-study.pdf.

The architect creates the architecture design document to document the design factors and the specific choices that have been made to satisfy those factors. The document serves as a way for the architect to show his work when making design decisions. The architecture design document includes the conceptual, logical, and physical designs.

How to do it...

The architecture design document should include the following information:

• Purpose and overview
  • Executive summary
  • Design methodology
• Conceptual design
• Logical management, storage, compute, and network design
• Physical management, storage, compute, and network design

How it works...

The Purpose and Overview section of the architecture design includes the Executive Summary section. The Executive Summary section provides a high-level overview of the design and the goals the design will accomplish, and defines the purpose and scope of the architecture design document.

The following is an example executive summary in the Cloud Infrastructure Architecture Case Study White Paper :

Executive Summary: This architecture design was developed to support a virtualization project to consolidate 100 existing physical servers on to a VMware vSphere 5.x virtual infrastructure. The primary goals this design will accomplish are to increase operational efficiency and to provide high availability of customer-facing applications.

This document details the recommended implementation of a VMware virtualization architecture based on specific business requirements and VMware recommended practices. The document provides both logical and physical design considerations for all related infrastructure components including servers, storage, networking, management, and virtual machines.

The scope of this document is specific to the design of the virtual infrastructure and the supporting components.

The purpose and overview section should also include details of the design methodology the architect has used in creating the architecture design. This should include the processes followed to determine the business and technical requirements along with definitions of the infrastructure qualities that influenced the design decisions.

Design factors, requirements, constraints, and assumptions are documented as part of the conceptual design. To document the design factors, use a table to organize them and associate them with an ID that can be easily referenced.

The following table illustrates an example of how to document the design requirements:

The conceptual design should also include tables documenting any constraints and assumptions. A high-level diagram of the conceptual design can also be included.

Details of the logical design are documented in the architecture design document. The logical design of management, storage, network, and compute resources should be included. When documenting the logical design document, any recommended practices that were followed should be included. Also include references to the requirements, constraints, and assumptions that influenced the design decisions.

When documenting the logical design, show your work to support your design decisions. Include any formulas used for resource calculations and provide detailed explanations of why design decisions were made.

An example table outlining the logical design of compute resource requirements is as follows:

Similar tables will be created to document the logical design for storage, network, and management resources.

The physical design documents have the details of the physical hardware chosen along with the configurations of both the physical and virtual hardware. Details of vendors and hardware models chosen and the reasons for decisions made should be included as part of the physical design. The configuration of the physical hardware is documented along with the details of why specific configuration options were chosen. The physical design should also include diagrams that document the configuration of physical resources, such as physical network connectivity and storage layout.

A sample outline of the architecture design document is as follows:

• Cover page: It includes the customer and project names
• Document version log: It contains the log of authors and changes made to the document
• Document contacts: It includes the subject matter experts involved in the creation of the design
• Table of contents: It is the index of the document sections for quick reference
• List of tables: It is the index of tables included in the document for quick reference
• List of figures: It is the index of figures included in the document for quick reference
• Purpose and overview: This section consists of an executive summary to provide an overview of the design and the design methodology followed in creating the design
• Conceptual design: It is the documentation of the design factors: requirements, constraints, and assumptions
• Logical design: It has the details of the logical management, storage, network, and compute design
• Physical design: It contains the details of the selected hardware and the configuration of the physical and virtual hardware

Writing an implementation plan

The implementation plan documents the requirements necessary to complete the implementation of the design.

The implementation plan defines the project roles and defines what is expected of the customer and what they can expect during the implementation of the design.

This document is sometimes referred to as the statement of work. It defines the key points of contact, the requirements that must be satisfied to start the implementation, any project documentation deliverables, and how changes to the design and implementation will be handled.

How to do it...

The implementation plan should include the following information:

• Purpose statement
• Project contacts
• Implementation requirements
• Overview of implementation steps
• Definition of project documentation deliverables
• Implementation of change management

How it works...

The purpose statement defines the purpose and scope of the document. The purpose statement of the implementation plan should define what is included in the document and provide a brief overview of the goals of the project. The purpose statement is simply an introduction so that someone reading the document can gain a quick understanding of what the document contains.

The following is an example purpose statement:

This document serves as the implementation plan and defines the scope of the virtualization project. This document identifies points of contact for the project, lists implementation requirements, provides a brief description of each of the document deliverables, deliverables, and provides an overview of the implementation process for the data-center virtualization project.

The scope of this document is specific to the implementation of the virtual data-center implementation and the supporting components as defined in the Architecture Design.

Key project contacts, their roles, and their contact information should be included as part of the implementation plan document. These contacts include customer stakeholders, project managers, project architects, and implementation engineers.

The following is a sample table that can be used to document project contacts for the implementation plan:

Support contacts for hardware and software used in the implementation plan may also be included in the table, for example, contact numbers for VMware support or other vendor support.

Implementation requirements contain the implementation dependencies to include the access and facility requirements. Any hardware, software, and licensing that must be available to implement the design is also documented here.

Access requirements include the following:

• Physical access to the site.
• Credentials necessary for access to resources. These include active directory credentials and VPN credentials (if remote access is required).

Facility requirements include the following:

• Power and cooling to support the equipment that will be deployed as part of the design
• Rack space requirements

Hardware, software, and licensing requirements include the following:

• vSphere licensing
• Windows or other operating system licensing
• Other third-party application licensing
• Software (ISO, physical media, and so on)
• Physical hardware (hosts, array, network switches, cables, and so on)

A high-level overview of the steps required to complete the implementation is also documented. The details of each step are not a part of this document; only the steps that need to be performed will be included. For example:

1. Procurement of hardware, software, and licensing.
2. Scheduling of engineering resources.
3. Verification of access and facility requirements.
4. Performance of an inventory check for the required hardware, software, and licensing.
5. Installation and configuration of storage array.
6. Rack, cable, and burn-in of physical server hardware.
7. Installation of ESXi on physical servers.
8. Installation of vCenter Server.
9. Configuration of ESXi and vCenter.
10. Testing and verification of implementation plan.
11. Migration of physical workloads to virtual machines.
12. Operational verification of the implementation plan.

The implementation overview may also include an implementation timeline documenting the time required to complete each of the steps.

Project documentation deliverables are defined as part of the implementation plan. Any documentation that will be delivered to the customer once the implementation has been completed should be detailed here. Details include the name of the document and a brief description of the purpose of the document.

The following table provides example descriptions of the project documentation deliverables:

How changes are made to the design, specifically changes made to the design factors, must be well documented. Even a simple change to a requirement or an assumption that cannot be verified can have a tremendous effect on the design and implementation. The process for submitting a change, researching the impact of the change, and approving the change should be documented in detail.

The following is an example outline for an implementation plan:

• Cover page: It includes the customer and project names
• Document version log: It contains the log of authors and changes made to the document
• Document contacts: It includes the subject matter experts involved in the creation of the design
• Table of contents: It is the index of document sections for quick reference
• List of tables: It is the index of tables included in the document for quick reference
• List of figures: It is the index of figures included in the document for quick reference
• Purpose statement: It defines the purpose of the document
• Project contacts: It is the documentation of key project points of contact
• Implementation requirements: It provides the access, facilities, hardware, software, and licensing required to complete the implementation
• Implementation overview: It is the overview of the steps required to complete the implementation
• Project deliverables: It consists of the documents that will be provided as deliverables once implementation has been completed

Developing an installation guide

The installation guide provides step-by-step instructions for the implementation of the architecture design. This guide should include detailed information about how to implement and configure all the resources associated with the virtual datacenter project.

In many projects, the person creating the design is not the person responsible for implementing the design. The installation guide outlines the steps necessary to implement the physical design outlined in the architecture design document.

The installation guide should provide details about the installation of all components, including the storage and network configurations required to support the design. In a complex design, multiple installation guides may be created to document the installation of the various components required to support the design. For example, separate installation guides may be created for the storage, network, and vSphere installation and configuration.

How to do it...

The installation guide should include the following information:

• Purpose statement
• Assumption statement
• Step-by-step instructions to implement the design

How it works...

The purpose statement simply states the purpose of the document. The assumption statement describes any assumptions the document's author has made. Commonly, an assumption statement simply states that the document has been written, assuming that the reader is familiar with virtualization concepts and the architecture design.

The following is an example of a basic purpose and assumption statement that can be used for an installation guide:

Purpose: This document provides a guide for installing and configuring the virtual infrastructure design defined in the Architecture Design.

Assumptions: This guide is written for an implementation engineer or administrator who is familiar with vSphere concepts and terminologies. The guide is not intended for administrators who have no prior knowledge of vSphere concepts and terminology.

The installation guide should include details on implementing all areas of the design. It should include configuration of the storage array, physical servers, physical network components, and vSphere components. The following are just a few examples of installation tasks to include instructions for:

• Storage array configurations
• Physical network configurations
• Physical host configurations
• ESXi installation
• vCenter Server installation and configuration
• Virtual network configuration
• Datastore configuration
• High availability, distributed resource scheduler, storage DRS, and other vSphere components installation and configuration

The installation guide should provide as much detail as possible. Along with the step-by-step procedures, screenshots can be used to provide installation guidance.

The following screenshot is an example taken from an installation guide that details enabling and configuring the Software iSCSI adapter:

The following is an example outline for an installation guide:

• Cover page: It includes the customer and project names
• Document version log: It contains the log of authors and changes made to the document
• Document contacts: It includes the subject matter experts involved in the creation of the design
• Table of contents: It is the index of document sections for quick reference
• List of tables: It is the index of tables included in the document for quick reference
• List of figures: It is the index of figures included in the document for quick reference
• Purpose statement: It defines the purpose of the document
• Assumption statement: It defines any assumptions made in creating the document
• Installation guide: It provides the step-by-step installation instructions to be followed when implementing the design

Creating a validation test plan

The validation test plan documents how the implementation will be verified. It documents the criteria that must be met to determine the success of the implementation and the test procedures that should be followed when validating the environment. The criteria and procedures defined in the validation test plan determine whether or not the design requirements have been successfully met.

How to do it...

The validation test plan should include the following information:

• Purpose statement
• Assumption statement
• Success criteria
• Test procedures

How it works...

The purpose statement defines the purpose of the validation test plan and the assumption statement documents any assumptions the author of the plan has made in developing the test plan. Typically, the assumptions are that the testing and validation will be performed by someone who is familiar with the concepts and the design.

The following is an example of a purpose and assumption statement for a validation test plan:

Purpose: This document contains testing procedures to verify that the implemented configurations specified in the Architecture Design document successfully addresses the customer requirements.

Assumptions: This document assumes that the person performing these tests has a basic understanding of VMware vSphere and is familiar with the accompanying design documentation. This document is not intended for administrators or testers who have no prior knowledge of vSphere concepts and terminology.

The success criteria determines whether or not the implemented design is operating as expected. More importantly, these criteria determine whether or not the design requirements have been met. Success is measured based on whether or not the criteria satisfies the design requirements.

The following table shows some examples of success criteria defined in the validation test plan:

If the success criteria are not met, the design does not satisfy the design factors. This can be due to a misconfiguration or error in the design. Troubleshooting will need to be done to identify the issue or modifications to the design may need to be made.

Test procedures are performed to determine whether or not the success criteria have been met. Test procedures should include testing of usability, performance, and recoverability. Test procedures should include the test description, the tasks to perform the test, and the expected results of the test.

The following table provides some examples of usability testing procedures:

The following table provides some examples of reliability testing procedures:

These are just a few examples of test procedures. The actual test procedures will depend on the requirements defined in the conceptual design.

The following is an example outline of a validation test plan:

• Cover page: It includes the customer and project names
• Document version log: It contains the log of authors and changes made to the document
• Document contacts: It includes the subject matter experts involved in the creation of the design
• Table of contents: It is the index of document sections for quick reference
• List of tables: It is the index of tables included in the document for quick reference
• List of figures: It is the index of figures included in the document for quick reference
• Purpose statement: It defines the purpose of the document
• Assumption statement: It defines any assumptions made in creating the document
• Success criteria: It is a list of criteria that must be met to validate the successful implementation of the design
• Test Procedures: It is a list of test procedures to follow, including the steps to follow and the expected results