“The only difference between a mob and a trained army is organization” – Calvin Coolidge
Have you ever come across a model that was more of a mob than useful tool? I have! Systems Engineering is partly an effort in organizing your systems information and concepts in a way that makes logical sense, allowing you to communicate the relations between all the different aspects of a system in a coherent manor. In order to do this, we must organize our model and make it easy to navigate.
I’ve witnessed many modeling organizational methods that make navigating the structure of the model difficult. Too often little thought is given to the model organization. To the engineer actively building their model, whatever structure (or lack of) they give the model makes sense at the time, but does it help another person understand the model later on? I’d like to take a step back and discuss organizing our models in meaningful ways, and share some best practices I’ve accrued over the years.
Do you spend time organizing your computer files? Or do you let files pile up on your desktop? I admit, sometimes my PC’s desktop gets pretty cluttered with working files, and when that happens I take a step back and spend a few minutes organizing the mess and getting rid of un-needed files as well. In a few months, or maybe even a year later when I need something that I had just scattered on my desktop, I thank myself for spending the time to organize my files.
Working in GENESY is a very similar situation to this. Models are built both graphically and textually. When generating new entities in the diagram framework, unless you specify the location specifically, they go into the top-level folder. This is much the same as when I temporarily save files to my computer desktop for expediency. When I do this, I know I will have to go back and clean up my model (or desktop) in order to file away the information in logical place.
So, how do we organize our GENESYS models? GENESYS organizes data according to its schema. It’s the set of containers for the concepts we’re using to represent different aspects of our system, the attributes of each of the conceptual areas we’re working with and the relations between these concepts. The first line of organization is the schema, each class in the schema is shown in GENESYS as a folder in the project explorer. The class name is the top-level folder. When you create entities, they get put in folders. The key to a well-organized model is to do the same sort of organization you do with your desktop folders to your folders in GENESYS.
Below the top-level class folder, GENESYS allows you to create as many folders as you want, the same way all common operating systems allow you to create folders to organize your files. Use the GENESYS folders to organize the entities you create in each class. If you create a logical set of folders in each class you’re modeling, you can encapsulate different aspects of the architecture in organized sets that makes it easy for someone else who will come in later and have to navigate the model to find the information they’re after easily.
What’s the best approach to organizing the folders? The answer to that is, of course, dependent on the class you’re dealing with and any particular constraints of your organization. But typically, I find the decomposition of the model suggests the folder structure. For instance, consider the following component hierarchy:
I would want to create folders in my model that follow this breakdown. Doing so would help the next engineer to easily find the entities related to each subsystem. My folder structure might look something like this:
In this example, I created a folder to house the system context components, and then created folders for my System of Interest (SOI). It may not be necessary to create sub folders for the System Context level, as those all exist at the top context level, but we do want to create subfolders under the SYS Video Drone folder in order to clearly identify the subsystem breakdown. For a physical architecture best practice is to create a folder for every major subsystem, and perhaps create folders underneath the subsystem components to organize all the part level subcomponents. The level to which it makes sense to create a folder structure for is dictated by the level of the design.
Always try to leave the top-class level folder empty! This is good practice and will make your cleanup tasks easier. In the GENESYS diagram framework, when building out the model graphically, if you select the “New [whatever main entity for the diagram you’re working in is]” and drag and drop it on the diagram, guess where GENESYS is going to create that entity in the Project Explorer view? Right in the top-level folder, that’s where! If you leave the folder purposefully blank when ever this sort of entity creation happens, that entity ends up in the top-level folder, which make it easy to find and then move into its proper folder. Any entities in a top-level folder haven’t been filed away yet!
Let’s shift gears a little and take a look at organizing the Function class. Functions should be organized hierarchically just like Components. As your physical hierarchy breaks down so do the functions that those components are performing, therefore they should be organized similarly to the Component structure. If we think of our Component hierarchy as analogous to our specification tree, we can clearly see the Functional hierarchy has to decompose the same way. Here’s how I’ve organized the Drone model’s Function class:
As you can see, the class level folder (the top folder) is empty, and folders were created that are very much in line with the Component folder structure, starting with a folder to hold the Context Functions, and then a folder to organize our SOI’s functions. Note the one difference here in the Function class, as part of the modeling process we’ve done a threads analysis. Remember that thread functions should exist independently of system functions, and because they need to be preserved, the best practice is to create a separate folder to organize you threads.
You may be wondering why the Phone Application function folder is empty… I’ll give you a hint – “Cross Project Relations”. The phone application model is separated into another project to demonstrate this capability. When models are split this way, build the folder structure out in the main model. That way users can easily see that there are phone application functions, and where they exist in the organization of the model. I also replicate the similar levels of folders over in the other project, for the same reason, it helps the engineer to understand where they are in the hierarchy. Below is the folder hierarchy in the Phone Application project.
When you’re building your models a good rule of thumb is to make sure that the entity at the top of a folder is the entity you would like the engineer to open a diagram on first. For example, when you look in the organized function folder you’ll find the “CF Context Functions” folder first. When you select that folder, the entity at the top of the list should be the starting point for opening a diagram. In that folder the first function is “CF _Perform System Context Function”, which is the top level of the function model, if you open an EFFBD or an Activity Diagram on that entity you’ll be at the beginning of the functional model. If you select the “SYSF Drone System Functions” folder, you’ll find a single entity, the “_Perform Video Drone System Functions”, which you can open and see the Drone system functions. Use numbering to get it there if you need to, but make it easier on your model users to navigate by always following that simple rule. If the model user can always expect to find the entity you want them to open at the top of the folder, it makes the model easier to navigate.
A lot of other tools rely on organizing their models by package or containment tree, where the package definitions and structure do all the organization. While you can do this in GENESYS using packages, why would you, when the tool is already structured according to the defined classes? Simply organize the classes with folders, and then follow the relations from the organized entities to the rest of the model. It’s simple and intuitive using natural language based on the use of named relationships. The model organization should help the user navigate the model, and allow them to find what they’re after quickly and easily. Don’t create a mob of a model, instead create a trained army of relational data!
