02 Jul What’s in an EA Repository

Joe Roushar – July 2018

Context of Enterprise Architecture

Understanding context of systems and data in an enterprise is essential for successful IT project alignment and portfolio simplification. Enterprise architecture frameworks such as Zachman, Archimate and TOGAF provide great mechanisms for documenting systems and data, and architecture diagrams are often worth much more than a thousand words. But what good are documents unless the people who can benefit from the knowledge they contain can easily find and use them? Furthermore, how can you ensure they are correct unless the business stakeholders understand them well enough to identify errors and omissions.

Today, I’d like to share my experiences and ideas about maximizing the value of architecture documentation by deploying it using an intranet-based portal or consumer repository that empowers users through good organization and rapid search. Besides talking about what’s in an EA repository, I’ll describe my ideas about the repository characteristics that optimize the value to users of all stripes.

Collaborate to Share Understanding

Technical jargon can be very dense, and even among technicians, one person’s description of what they built can be difficult to understand. This difficulty in understanding is compounded when the consumers of the information are less technical, such as managers or business stakeholders. Project people who are responsible for implementing enabling technologies benefit profoundly from being able to review reference architecture diagrams whenever they need them, particularly during the design process.

When architecting a solution it is important to ensure the solution meets business needs. Often, some of the most important people to validate the architecture and design are business users, managers and directors who may have limited technical background. Making the diagrams easy to find and examine is critically important to empowering project teams and stakeholders with the information they need. It is even possible to make project team collaboration sites part of the repository itself. Collaboration, in general, is enabled and improved by first drawing meaningful pictures that accurately depict complex technical components, then delivering them in a user-friendly way to all stakeholders. The usability of the diagrams is critical as well, but I’ll address that in another post.

What are the optimal characteristics of a consumer-oriented Architecture Repository?

I have built and used such repositories with tools including Orbus iServer, Planview Troux, SharePoint/Teams, Atlassian Confluence and Sparx. The diagrams have been created using proprietary tools, as well as Visio and Illustrator, and everything in between. Each of these approaches have strengths and weaknesses. Smaller organizations may not be able to afford a tool such as Aris Alfabet, Avolution, Mega,  Sparx, Troux or iServer, though they can bring tremendous value to the process (see Gartner MQ). For a good article on selecting an EA tool for a formal repository, check out this link.

At both Scott County, Minnesota, and UCare, I built SharePoint-based repositories that were widely used and significantly helped in improving project alignment and portfolio simplification. In both cases, the artifacts were almost exclusively built in Visio, with some content in HTML, SharePoint lists and office documents in PowerPoint, Excel and Word. Repositories based on EA Systems can also leverage widely available diagramming tools, and I have used Orbus iServer to build an extensive repository of Visio diagrams.

In the beginning, these were mostly used by IT people to get a better understanding of the systems portfolio, data and infrastructure. But soon, people on various projects began exploring the EA repository, and found that the information helped them better understand the interactions of things, and enabled them to better align solutions to achieve more standardization and simplification. Reducing the number of technologies through better alignment reduces the number of unique skills an IT department and an organization requires.

The Ideal Repository

I will provide a little more depth on the characteristics I proposed above. Why deploy to the Intranet instead of the repository native to an EA app? First, all your stakeholders typically have access to the intranet, and even if the content is buried deep in an application, if the content is deployed using URL-accessible pages, the intranet can act like a launchpad. Many intranets are based on a platform that has a Content Management System (CMS), and this is a good way to organize architecture diagrams and data. Whether your intranet platform is Adobe, NetWeaver, Sitecore, Confluence, WordPress, Teams or whatever, the ability to organize pages, create clickable images and optimize a hypertext navigation model enables you to deploy all the relevant content to stakeholders.

My preferred structure for the repository home page is a handful of meaningful, distinct and appropriate pictures with simple labels. In the illustration here, you see each of the EA domains as a clickable picture (link) that leads to the home page for that EA domain. Each domain, in turn can have labeled pictures pointing to sub-domain pages that contain the information users need. At the domain level, you can even use a “Mall-Map” or “Place-mat” style diagram of the entire domain with clickable regions using the HTML “image map” feature. There are free online image map generators that are easy to use to make images clickable by region. I have used a version of Visio that supports clickable, web-deployable images that are even better than image maps, but proprietary, thus less flexible.

You may have noticed a reference to a CMDB, or Configuration Management Database in the illustration. Architecture tools may contain a CMDB or something like it, but normally do not. These are more commonly part of an IT Service Management tool. Erik van der Voorden describes some of the pros and cons of integrating the EA repository and an external CMDB. Connecting an architecture repository to related external content will make it more robust. Doing so could make it more confusing, so it is important to provide context, such as “bubble” explanations of each clickable object on a page. Because of the simplicity of adding HTML to a page, this kind of content may be added later, but if it is part of the original plan, you can avoid the sense that the site is growing more complex and less usable.

Access Controls

Architecture diagrams typically contain no personal sensitive information, credit card numbers or sensitive health information. Thus compliance is not typically specified in government regulations or standards. Many architecture artifacts contain no sensitive information for people within an organization, so could be shared universally with employees and contractors with internal access credentials. Some things such as strategic plans, confidential roadmaps and IP addresses, however, should be restricted to those with a need-to-know. When your architecture repository is contained in a proprietary system, limiting access is often straightforward because you only grant access to those for whom you can justify buying a license. When using an intranet platform, however, access controls are a bit more complex, and often delegated to page creators. When establishing an architecture repository, remember to establish clear standards and periodically check and make corrections where needed.

The question of access control leads to a more fundamental question: what is the scope of the EA Repository? Harald van der Weel points out that an EA Repository may be scoped smaller or larger than the organization. We might ask:

• Is the repository to encompass the complete organization, or some subset of business units?
• Does the repository to encompass include parent/holding companies or other subsidiary companies (siblings)?
• Are partners, distributors, suppliers, customers or other related-parties in scope in an integrated EA repository?

Naturally, the wider the scope, the more difficult managing access controls as well as generating and validating the artifacts will be.

Reference and Target Architectures

The section of the repository labeled “Reference” may contain reference and target architecture artifacts. Reference architectures can help align current project designs. They serve as cornerstones for building new capabilities, and are often based on successful implementations, thus providing not only illustrations to help designers, but functioning solutions as examples. Target architectures are more aspirational and futuristic. Consequently, there may be components that have no examples in an organizations current systems. While aligning new designs to reference architectures is relatively straightforward, target architectures can be more difficult because of technical distance between the current state and the proposed state, unfamiliarity with the proposed technologies or ambiguity in the proposed architecture.

In the illustration above, I showed the Reference architecture section divided by EA domains, but dividing by business domains may be a very good alternative. Examples of business domains could be fairly course grained, such as Sales, Marketing, Finance, Products, IT, Admin/Legal/HR. Finer-grained models are justified when you need to have more domains up front to achieve 80 x 3. Examples could include putting lines of business or regions on the home page.

The artifacts that are most useful to the IT folks, especially engineers, are very technical. Often UML diagrams such as Use Cases, Package Diagrams and Sequence diagrams can be good ways to communicate technical architectures. For non-technical stakeholders, however, the illustrations need to be tailored to their world views, and often look less like schematics and more like cartoons. I exaggerate. But you’ll note in the first illustration in this post, there is a range of different diagrams, some with lines that represent touch-points or integrations, and some only with blocks and nested organization. Visual elements of architecture diagrams should be arranged to maximize meaningfulness for the intended audience, and the same rule applies to the EA portal or repository as well.

Standards and Guidelines

IT organizations are often very fluid because of the mobility of workers, so it is likely that many of your IT customers are new, and may not be familiar with the way things are done in your organization. Lists of DO’S and DON’TS are not the ideal approach to win the hearts of internal customers who rely on EA to provide foundations for alignment and simplification. Standards and Guidelines can be delivered in gently prescriptive ways that encourage adoption rather than forcing compliance with EA dictum. But not publishing standards and guidelines can be damaging, in that designers may come from companies with completely different standards and guidelines. Without clear statements of direction, projects and solutions can diverge quickly.

Likewise, lists are valuable information, as long as they are easily consumable. I have found that data tables and SharePoint lists of no more than a few dozen elements are usable, but when they grow much larger, they rapidly become too much work for many users. When repository data can be deployed using Analytics or BI tools, especially longer lists such as Systems Portfolios, Capabilities and Services Lists, users can slice and dice them to visualize the data more meaningfully.

Project Architectures and Threads

Many organizations use intranet portals to create project collaboration sites that serve as home-base for project stakeholders to exchange information. Architects and IT leaders have vested interest in helping projects align, so it can be a natural choice to co-locate the EA repository with the Project Collaboration platform. This makes EA more “social” and this, in my perspective, is a needed improvement. I’ve seen this successfully done with both Microsoft and Atlassian collaboration tools, and each are gradually improving. Social capabilities such as comment threads supporting online dialog, blogs for posting important developments and Wikis for cross-referencing related information and artifacts make repositories more “sticky”, appealing to users who are eager to share their perspectives.

Not all individuals or cultures are ready for collaboration at this level, so it may be best to keep project sites separate from the EA repository, but this is a good option for organizations that fit more socially interactive models. A key point to remember here is that a culture of standardization will make these repositories and collaboration spaces much more effective and usable. Sprawl is a hazard, and some level of governance is often helpful to prevent or tame the expansion of such a repository. Ideally governance responsibilities are distributed to the owners of each domain and project.

Whether you choose to purchase a commercial EA tool with its own repository and/or portal, or build your architecture repository from available tools and materials, it is important to deploy the content so it is findable and usable by those who may be able to influence the technical direction of projects and purchases. Ideally, well defined architecture artifacts can help move organizations toward alignment and simplification. Achieving this often involves commitment to work, investment, and some culture change to optimize the value EA can bring to IT.