Creating an architecture diagram

Video transcript

Hello and welcome to the IBM Cloud Docs architecture design framework.

This page is gonna be the creating and architecture diagram and we will look at a few of the sections within this page.

We'll start with the library's stencils and shapes and that will take us into this link for the IBM Cloud architecture stencils.

So once I click on that, we'll scroll down here and we'll see there's certain sections. The first section we're gonna look at is the draw.io we'll click on the click here to expand and now you'll see in this section we have getting the draw diode desktop application and distent inventory.

So let's look at how to get the desktop application. If you click on the jgraph drawio repo site, it will then bring you to the page where you can download the draw.io desktop and we will start from the latest version which is 24.7 0.8. And if you scroll down, you'll now see all the assets for downloading. You've got windows installers and Mac OS installers. And then there's also a couple of opportunities for Linux if that's what you need. And as you scroll down, you can see we go to the previous releases also.

Now we come back to the draw.io page and we scroll over to the draw.io stencil section. And now here on the left, you can see we've got all the different categories of icons that are available through IBM Cloud. You can see, come down here, we've got devops actors. So let's click on the actors. We'll go here to the raw section and then go up the top and click save page as we'll send that to our desktop. Come back and open that. Now we've opened our draw.io program and we go down to file, open the library and go to that IBM Cloud actors XML library, we saved and open it. Now you'll see on the left hand side, we've got version 1.0 0.1 of IBM Cloud users. So now we've got all the different users that we have in IBM Cloud.

So if we go back to the architecture icon section, you'll see this one file called ibm_all_in_one. And so if you click on the ibm_all_in_one file and go back over to the raw button and then save the page to one of your files, then come back to draw.io. And if you open up that file or the new library and it's the all in one. You'll now see that we have all of the IBM icons in one folder. So the top here will be all of the containers and everything is alphabetical. So you could scroll through alphabetically find what you need. So we're just gonna pull a little data center container out here. Then the icons are the same, they're all alphabetical by user. So the first section is users. The second section is A I and then these down here compute, the green ones. So you can pull these icons straight onto this data center box and drop them into the container. Now you'll notice that the icons all now move along with that re retainer, they're in a container, so they will move if you move the data center and you'll see if you pull this back in, you'll see the blue line outlying the data center that's letting you know it is now contained.

So the next section we're gonna look at is the IBM connectors. So if you click there and open and then we'll save it just like we have in the past. Click on raw, save the page as into your desktop or laptop and then open up draw.io and go to open the library. You'll now see the IBM connectors XML. So we open that up and now here are all of our connectors with the annotations below them. Makes it very easy to find. So let's just pull in a couple of icons here. We'll put in a user and we'll connect these. So we need to go and grab the icon or the connector that we need. And now we can just connect the two icons together with an annotated connection.

Now, Jose has created a de facto table of contents for the icon. So if you click here, you'll now see a table of contents of all the icons that are available in the categories. And it'll show you if there's an alternate name, the stencil occurrence for that icon and then which library it it lives in. So if you wanted to find the IBM cloud stencil, you'll find it in IBM Cloud groups and it'll be so much easier for you to locate them if needed.

We also provide some templates to make it a little easier for you to get started. So if you come down to the 2.0 templates, open up this file, you'll see, we've got four templates, go get started. So the same thing, if you double click on one of these, then you click on the raw, save that page as a file on your workstation and then come on over to draw.io to a file open. This is not a library, it's now a file. So we're gonna just open it as a regular file there. It is we'll open it. Now, you can see we have a template already created that you can get started with.

Now, if we go back to the main IBM Cloud stencils page and start scrolling down, you'll see the next section is powerpoint. We've created a powerpoint tool for those of you who want to design diagrams and powerpoint. This section has the actual powerpoint itself and then we also have a video tutorial on how to use it. And there's some good sections in here, especially one on how to make your own icons, which we'll talk about here in a second. So if we click on the link and we download the powerpoint, open it up in powerpoint, you'll see there's a few sections talks about, about color, some examples how to scale some elements, the connectors once again. And then we have all of the icons currently being used in the IBM Cloud that we've created for draw.io. So they're all here for you to use down here to the groups. Now, if you come to this, create your own icons, we've given you colored boxes. And then if you see this link here, if you copy this link and place it into your browser, it will then take you to the IBM Designs UI icon site. So this is all of the icons that IBM has created through their design team. There's a search bar. So if you type in cloud, you'll see a lot of the app icons that are used for cloud, the data cloud icons and then you'll see in the bottom right corner, there is the download button. So you'll just download that button. Go back to the tutorial that was provided and it will talk you through how to change the color of these icons from a black to white and then how to place them into the colored boxes that are provided.

The next section we'll talk about is the scalable vector graphics or the SVGs. Now, this is for the folks that are using Adobe illustrator or sketch or any other design tools that need the dot SVG files. So you can see each one of these folders here has the dot SVG file. And if you click on them over here, on the left hand side, you can actually see what that icon is. And then once again, you can click raw and then download the entire icon and save it to your folder on your desktop and utilize it in any of the design tools that need dot SVGs.

The next section we're gonna look at is the tools and conventions. So under this, we have format and layout colors and connectors. So if you click on the format and layout, twist it, you'll come down here and talk a little about the theory behind our containers and how we build architecture diagrams here at IBM. And as you keep going down, it'll give you just a little bit more information on how to define and design them under the colors twist we'll show you a color legend showing you what our boxes and icons mean. So the colors are now defined by the colors you see above. And then the second section, they will actually give you the hex numbers for those icons if you need to change or create different color boxes also. And then the third one is connectors which we've gone over a couple of times. But there is kind of a description of what our connectors look like and what they mean by the shapes and colors.

The final section in this part is the help and support. So if you have any request for icons that are not available or if you have any issues or any questions, you can always open an issue at github here and head up to the top right section, create a new issue and those will be directed to our team. We can work with you on any request or concerns or questions you might have to help us make the product better.

Ok, so let's go back to where we started. They're creating an architecture diagram page in Cloud docs and I can see here the library of stencils and shapes we've done that. We've gone through the IBM Cloud architecture stencils and, and get that. Installing the stencils and shapes we've shown you guys how to do that. And then in this section here, it talks about how to create a diagram. So it goes through the steps of creating the diagram, but you'll see there's this other link here that has been provided and this is a link to adding IBM Cloud service icons. So these are the icons that live on IBM's Cloud catalog. These will be specific IBM products or third party products that are on the IBM Cloud. So we'll go ahead and save that as we've done in the past, go to file and say page as it's default of this draw.io but you can put anything you want, come over to draw.io open a library and once again, we find the draw.io and now your service icons populated here on the left and you can see as you hover over them, the name of the icon shows up. But once you pull them in, you'll notice that there is no name attached them unlike the icons we were working with before that have the names coming with it. So come over here to your text section, create your font. IBM uses IBM Plex Sans. We use a 14 point font we position it on the bottom and then come down to spacing and put a minus seven and that will kernel it it up to the bottom of the icon nicely. So there you have it. IBM service icon with the name of the icon. You did it on the bottom.

Library of stencils and shapes

IBM Cloud provides a library of stencils and shapes to use in draw.io. This makes it so that all diagrams are using a standard set of shapes, colors, and flows.

However, IBM Cloud's approved design tool is Draw.io we have also provided PowerPoint (.ppt) and SVG (.svg) files for your convenience. You can access the IBM Cloud Architecture Stencils in GitHub.

IBM stencils and shapes can be of any of the following formats:

• Boxes that represent a deployedOn relationship for locations (logical, virtual, physical) of platforms, infrastructure, network, and so on, on which services and applications are deployed.
• Groups that represent a deployedTo relationship for grouping services and applications that are deployed on boxes.
• Nodes that are meant to represent stand-alone components or devices.

For example, a virtual server instance is deployed on a subnet and deployed to a security group.

The stencils are also organized by type, function, or purpose by using the following categories:

• IBM (Core): Components that are typically technology and brand independent or not associated with a specific IBM Cloud offering or service. Examples: Server, Router, Database, Application
• IBM Cloud: IBM Cloud specific offerings and services. Examples: IBM VPC, Classic VSI, Serverless, Internet Services, Security-Group.
• IBM Domains or Industries: Extensions that are focused on IBM specific non-Cloud domains and industries. Examples: Automotive, Retail, Blockchain, Watson.
• 3rd Party: Third-party products or services. Examples: VMware, BigFix, Akamai.

Installing the stencils and shapes

The latest library was built in collaboration with IBM Design Language. You can install the IBM Cloud Architecture Stencils for draw.io from architecture-icons.

Creating your diagram

Before you create your diagram, follow the instructions to download the IBM Cloud stencils in Getting stencil libraries compatible with draw.io application.

To start creating diagrams, open the draw.io application.

1. Select Create New Diagram, then click Create.
2. Go to File > Open Library and browse to your where you downloaded the IBM Cloud stencils, select the XML file, and click Open.
3. Optionally, add the IBM Cloud service icons.
4. Create the layout of the diagram from left to right (west to east) to represent the public traffic flow orientation.

Exporting your diagram to SVG output

1. Go to File >> Export as >> SVG...
2. Keep the defaults and also select Transparent background, Embed images, Embed fonts, and Open in a New Window.

Make sure that the Include a copy of my diagram is selected so that when you share the output with others they can open the diagram and edit it again when the SVG file is imported into diagrams.net.