How to write a design document for Azure

In my first post on cloudelicious, I write about the importance of planning, going through required decisions and capturing those decisions and cornerstones in a documentation. The idea of this article is to share insights from my experience how you could write a design document for Microsoft Azure, addressing the most important topics with a right balance between amount of content (amount of pages) and technical depth (level of details) / with hope that the document’s value is at its max.

While probably everyone agrees with the statement, before using a new product or service in production, it’s required to have a plan in place which addresses the “why”, “what” and “where” there is usually a push-back on those planning efforts. Don’t the comments below somehow sound familiar?

Design documentation is a waste of time…

… no one reads design doc’s!

However, why is it so difficult to find a good design document? Is it because people don’t know what to write? Would be surprising, as the consultants doing the implementation usually are very knowledgeable about the technology. However, there are a few common mistakes I regularly see in projects all around EMEA, which can make the acceptance of a document difficult:

• … architects tend to over-engineer;
• … design documentation is explaining how a feature work instead of describing a design decision;
• … people get lost in the details of a document and don’t find what they are looking for;
• … most documentation rarely is kept up-to-date as the project progresses;
• … people tend to forget which questions they need to answer during the writing;
• … the document tries to answer all questions for all possible audiences.

What people often underestimate, a design document is like a written contract between you, your customer or manager and the project team. When you document your assumptions, decisions, risks, etc., you give others a chance to agree with the scope. Naturally, requirements are going to change sometimes. Especially with the public clouds where new features are getting released on a very high frequency – almost on a daily basis. As technical details are going to change over time, it’s even more important to build a general design as a foundation to start from.

The concept of a design document

A design document is a way to communicate to others what the design decisions are and why the decisions taken are right decisions. The most significant factor that determines if a design document is useful is if it clearly explains the author’s intentions. Architects should want to share their ideas, and engineers (and other team members) should want to know what they’re building. At some point, someone will have to implement this design, so we want to make the knowledge transfer as smooth as possible.

Have a look at the tips below and understand how this could be adapted when you write your next design document for Microsoft Azure:

Structure your paper – start with the table of contents with the most important chapters of the document and drill down one level after the other. Once the TOC is complete, add bullet-points to indicate the content that goes into these chapters. That way, you feel if the structure is right – and you have an indication of whether your structure is clear, walks the reader through all essential topics, is logical to follow, and rules out repetition.

Keep it short – Quantity doesn’t automatically make a good document. Short documents are easier to read and lot more comfortable to maintain to keep the content up-to-date. Don’t duplicate content or copy & paste text from the Microsoft Azure Documentation library. Instead, add a footnote and refer to the online article for people who maybe don’t have the required background.

Capture the decisions – A design document is all about decisions to meet the requirements. You should always be able to list at least one compelling reason, related to the conditions, for why a design decision was made. That reason must be kept and documented. If you can’t come up with an apparent reason for a design decision, then it is probably not adding enough value. Having the context will make it much easier to handle also the politically of a project.

A picture is worth a thousand word – Pictures or diagrams are an excellent tool for visualizing a design, but they cannot convey the motivation behind a design decision. Adding supporting text and refer to the picture is very important to structure the document. Don’t forget to use captions for more accessible reference. Important, leverage pictures to supplement a design document, not be a design document.

Separate details from content – Details such as a list of server names, or IP Addresses make a design document unnecessary long and hard to read. Why not move this information into appendices or refer to an external document? Ensure to use keep the cross-reference working, don’t make people hunt for the information they want.

You eat with your eyes – The primary purpose of a design document is, of course, the technology. However, taking a little time to change out your fonts and ensure consistency in style can have a significant impact on how professional your documents feel. Don’t underestimate the importance of this task.[/vc_column_text][vc_column_text]It is straightforward, a design will typically be considered good if it fulfills the requirements in a meaningful way. If the document can transport this message, your job has been accomplished well.

The design document for Microsoft Azure

Does this seem like too much work? Usually, it’s not. A design document is following similar patterns and if you have a structure which works for you, keep it and enhance it during the next project or update. IP re-use is key and makes your work better every time you re-use the existing material.

Have a look at the Table of Content (TOC) below; it highlights the most important topics to include in a design document for Microsoft Azure:

1. Introduction
   Describe the scope of this document and who’s the target audience. Capture the design objectives, constraints, assumptions (if any) and appetite (or vision) for the cloud and make sure to add a quick summary as an overview.
2. Azure Architecture Overview
   A starting point to define which Azure Regions will be used. Also, cover topics like Subscription Model, Administrative Roles, Naming Standards, Role Based Access Control (RBAC) and Azure Resource Manager.
3. Microsoft Azure Networking
   Networking represents one of the most important chapters of the document. Things like Network structure, ExpressRoute, Virtual Network Address Space, Virtual Network Gateway, DNS, Network Security Groups, Forced Tunneling, … will go here. Move lists of IP’s to an external document or the appendix.
4. Microsoft Azure Storage
   Capture the decisions on the requirements for the workloads (e.g., path-through, IOPS), Storage Accounts, Managed Disks and Virtual Hard Disks. Encryption and Azure Files also would make an important part.
5. Microsoft Azure Compute
   Often we focus on Infrastructure-as-a-Service (IaaS) here, which would include information about VM Types, Instances, Availability Set, how Images will be documented and which VM Extensions can be used.
6. Microsoft Azure Identity
   Define how the existing on-premises identity and name services will be made available in Azure, and how this could get extended using Azure Active Directory (AAD). This doesn’t necessarily have to cover the AD or AAD design.
7. Compliance & Security
   Design Guidelines to ensure a secure adoption of Azure, including certifications for PCI-DSS (if required) and integration with Azure Security Center.
8. Backup
   Design Guidelines on Backup, ow the existing solution will be used for the cloud or how Azure Backup would be used. Ideal chapter to touch on the requirement of Disaster Recovery, cloud to cloud using Azure Site Recovery (ASR).
9. Management and Maintenance
   Decisions on how the newly deployed services will be integrated into the existing monitoring and patch management. Position Log Analytics, Azure Automation and other management capabilities to support these activities.
10. Appendix
    Move the full naming convention to the Appendix. The end of the document is also an excellent place to keep all links to the online resources.

You can find further insights on the naming convention for Azure Resources in our next blog post. This article can be helpful when you start your own Azure Design.

There’s just one more thing…

In this article, I shared my thoughts and practices how to write a design document for Microsoft Azure and also indicate how important the creation of such is. Of course, “there isn’t just one way of doing it”, and every customer has their requirements or preferences. People are crucial to success in every project, and especially when you define the cloud platform for your servers and applications. You most likely want to bring your A-Team to the design workshops. Have a look at the article describing the different flavors of an architect; this might positively impact your staffing.