Documenting Your Azure Architecture: Azure One-Sheet
As your project grows, so should your documentation. Today's post revisits the One-Sheet, but with an Azure twist.
When new developers are added to the team, they need brought up to speed relatively fast when it comes to documentation. They want to know where the code is, what is the architecture, what's the roadmap, etc.
Documentation of your projects is very important. You want the developers to hit the ground running. So how do you easily let the developer know about all of the components of the project they'll be touching?
That's where the One-Sheet comes in.
This was first used in the entertainment industry and wikipedia.org defines a one-sheet as a single document that summarizes a product for sales and publicity. This concept caught on with music, layouts, and design.
I thought this was an absolutely brilliant idea and decided to use One-Sheets for software projects.
I mentioned One-Sheets a while back with some downloadables, but with cloud projects appearing more frequent, I thought this would be a great time to introduce the Azure One-Sheet I've been using over the past year.
Consider them like an "Executive Summary for Developers."
Documenting Your Azure Architecture
When a new developer is hired on (or existing developers are brought over to help out) to complete enterprise projects, handing a One-Sheet to a developer would give them enough to go on before the next status meeting.
We recently brought in a lead developer and they wanted to know where code was located, what was connected to what, oh...and where is DEV, QA, and PROD?
We provided a One-Sheet to the developer and it answered all of his immediate questions. When he was done reading it, he exclaimed "This is really cool. Most projects should have these."
Hence, the reason for the post. :-)
What To Include in Azure Documentation
If you are building cloud applications, whether it's Azure or AWS, take a look over the list and see if anything's missing where it may be critical for a new developer.
- Overview - Description of the project; why it's being built; purpose
- General Project Information - Location of source; List of projects, languages, and technologies; Web Urls for DEV/QA/PROD
- DevOps - Defined CI/CD process; Location of build and release definitions
- Database Servers - Location of Database Servers; Connection Strings
- Azure Resources - Subscription; Resource Groups for the Project; Assets like Logic Apps, Azure Functions, Web Services, etc.
- Internal/External Dependencies - Incoming and outgoing calls; What external resources does this project touch?
- Communications - Where does everyone discuss the project? Teams? Slack? Twitter?
- Additional - Catch-all category; Miscellaneous
As you can see, when you hand this to someone, everything is consolidated onto this one sheet of paper explaining everything they need to start work on the project.
Conclusion
One-Sheets have been valuable with projects I've worked on in the past. Every large project I've worked on with clients contains one of these sheets. It gives me a 50,000-foot at-a-glance view of the project and refresh my memory as to where everything is located.
Of course, the one drawback to this approach is the documentation should always be current. So I know how hard it is for developers to keep the documentation in-sync with the project.
I hope these downloadables help with your projects.
Also, if I am missing something from the list, please post your comments below and I'll add it to my list above with credit to the submitter.
Have you created any One-Sheets for projects? How do you document the project? Post your comments below and let's discuss.