The next submission date is approaching and a few people are asking how important are the supporting docs.
The design document is in my opinion the most important area, however it is just one area of the submission.
Once a design is created, how does an architect prove the design meets the requirements in the real world? How does an architect ensure the solution is not an operational nightmare for other teams?
In large projects, it is quite common, for the architect to create the design documents and not actually implement the solution.
How does an architect ensure that the design is operationally ready?
This is where the supporting documentation comes in.
Installation & Configuration Documents
Depending on the type of company, outsourcing or operational structure the level of detail in these documents vary.
Personally, the approach I used for my successful VCDX submission was a joint installation and configuration guide.
To create a valid document I used the following approach.
- Assume some pre-reqesuite knowledge (cited in the auidence section of the document).
- Give a high level overview / component interaction diagram.
- Outline the order of configuration (Installation approach )
- Provide links or references to standard documentation (URLS provided / exact pages)
- I did not recreate the standard install information (no point its in the Urls provided)
- Provide the necessary configuration \ inputs information to install the design components.
Put yourself in the documentation review panel position.
Would you want to read through install steps over and over again looking for information, or would you rather have a link to a doc and some clear tables / inputs to configuration items and installation approaches?
Configuration Areas Example Ideas.
- Racking information and Rack layout
- Host Names
- IP Config
- DNS / NTP constants
- Storage parameters –
- cabling references / Ports
- Multipathing configuration (PSP/SATP)
- Initial Datastore configurations
- Networking parameters
- SRM – Recovery plans and site link configurations
- Virtual machine – template configuration
- initial nodes and IPs
Im sure there are other approaches to this area.
I’d recommend to make the documents your own. Avoid generic templates, and dont just use the partner SETS and reference architectures. Inspiration yes – copying I would avoid it.