Structure

Despite the great searching capabilities offered by Confluence, to work effectively with the big amount of information, it is also important to structure the pages intuitively so that it easy to navigate to pages even without searching. The first level of the structure defines "repositories", one for describing the current state of the organizational components and the other for the components changes. Each repository has a dedicated space:

Documentation Space

The Documentation space is meant to provide a snapshot of the current state of the enterprise. It includes information describing how the enterprise is structured, how it does business, and what systems it operates or uses. Since this information represents crucial know-how and is supposed to be used and trusted by dozens of people, it should keep the decent quality. Therefore, there should be more or less formal change management processes specifying how to manage the information in a controlled way. The exact approach depends on the needs of a particular organization. It could involve a review process that will verify each change before it is incorporated into the documentation, but it could also mean locking the space for modifications and letting just the specific group of people edit it.

The documentation structure copies the way the Enterprise Architect documentation repository is organized:

Enterprise Architect:

1. Business Architecture

The goal of the business architecture part is to provide an overview of the organizational capabilities, processes, business knowledge, and organizational structure. It basically describes what business is done in the company, how it is done, how the company is organized, and how it realizes value. Besides, it contains policies, rules & regulations, products & services, decisions & events, initiatives & projects, metrics & measures, and stakeholders.

Describing the business of an average organization will typically present a significant amount of information, so to keep the documentation manageable, it could be organized by domains. For example, a business architecture below shows separating the business of the bank into sections, each representing a single part of the business, such as accounts, loans, or payments. Domains could be further decomposed into smaller units until they have sensible sizes that are easier to describe.

Even though most information will be placed under some domain, there still will be information that is not specific to any topic and is possibly relevant to multiple parts of the business. Such information is placed aside from the domain structure. For example, LOAN Glossary contains business terms pertinent to the loans, while Glossary lists general terms not related to any specific domain or related to multiple.

2. IT Architecture

IT architecture represents IT systems and applications used or operated by the organization. It describes the components and capabilities of the systems, along with the information on how these systems are interconnected.

i) Systems

Organizations develop their systems internally by themselves, have them delivered by external vendors, or purchase them as ready-made products. The systems could be either operated on-premise, or they could run in the cloud. But irrespective of who delivered the systems and where they run, all systems in the organization must be documented for the following reasons:

• Analyst must know how the systems work to be able to find the best solution to the business needs
  • These systems directly support business processes so regardless of who developed the system, analysts need to understand them
  • Analysts need the documentation to describe required changes for the vendor
• Architects must know the systems to validate the proposed solutions and to continually improve the architecture
  • They need to know how to integrate the system with other systems
  • They need to understand the architecture of all systems to have a complete overview of the architecture of the whole organization
• If the systems were delivered by the external software vendor but operated by the internal team, they need to know its internal working to solve possible issues

ii) Systems - External

External systems are not operated by the subject organization, but they are equally important because they provide services and data that the internal systems consume (or they need services and data provided by the internal systems). End users do not directly work with external systems, so the only way these systems participate in the business processes is through system integrations. Even though they are not owned by the company, they are part of the IT architecture, and their existence should be documented. For each external system, it should be clear what its purpose is, what value it provides to the company, and what is the communication contract (inputs and outputs).

Systems Documentation

Every system, internal or external, is an artifact that is documented on its own page - the system overview. It serves as a "hub" aggregating all relevant information about the system, such as the system's purpose, main capabilities, and integrations with other systems:

Most large enterprise systems are too complex to be handled as atomic entities, so they are decomposed into logical modules, as it is shown in the following example. It also shows how system components, such as screens or functions, are represented as artifacts and are described by their own page. All these child artifacts pages are placed under the single parent "container" page - for example, all screens are under the CB Screens page:

3. Projects [Implemented]

Projects includes all changes which have been already implemented in the organization:

This section contains only the bigger projects which impact multiple enterprise components. Small enhancements and change requests are placed right under the impacted component (see CB Changes above, for example). Placing all changes under the projects would make the section cluttered and it is actually more convenient to have all related changes close to the impacted system.

The reason for keeping track of all past significant projects is tracing. After completing the project, no one will read the specification just like that. They will be looking for information only if an issue occurs. It is then priceless to have the possibility to take a look at how the project impacted the organization and why.

NOTE

Once the project has been completed, it is important to document it. Creating a short overview to introduce the project and listing its impacts on the organization does not take much time, and since the information is already fixed, no rework will be necessary. It is a well-invested time, and the people who will come after you will be grateful.

Projects and Changes Space

This space, which corresponds to the working repository in Enterprise Architect, contains ongoing projects and planned organizational components changes. Each project/change is represented by its own page:

Project documentation contains all the information needed to implement the change. This includes an overview of the change, requirements, analysis artifacts, design artifacts, architecture decisions, and so on. Unlike the "documentation" space, which is mostly static, this space frequently changes as the projects evolve.

Documents

From the implementation point of view, the most valued information lies in the artifacts specifications, which describe the analysis and design of the real parts of the solution. But besides the concrete analysis and design artifacts, most projects also need supporting materials that introduce the underlying business needs and which put the project in context. These are for example Business Requirements Document or Solution Description which are located under the Documents page:

While many companies are still creating these documents in the word processor, why not to use the Confluence and take advantage of its features? Besides, composing the documents in Confluence allows generating documents parts with the middleware, which increases the effectivity and prevents mistakes.
"But we need to send these documents to our customer", we hear you complaining. If your customer insists on getting the offline documents, the good news is Confluence has a feature to export a single page, selected pages, or the whole space to various formats, including Word and PDF. It is also possible to tailor the look and feel of the output to suit the needs of the customer. It is also able to exclude attachments and comments from the exported file, as well as some parts of the page using a special macro. Additionally, there is a couple of plugins that includes WYSIWG template editors, content filters, and other advanced features to make your PDF documentation look precisely the way your customers expect it.

Systems

While the Systems section in the Documentation space includes systems currently being operated or used by the company, here the section represents the future state, which means the systems or systems changes which are to be implemented:

Note: The same also applies to processes and other organizational components which are going to be changed within the project

ONE SPACE PER PROJECT

Putting all projects in one dedicated space has the advantage of keeping the repository organized, but there could be teams that may prefer to create a separate space for each project. The main advantage of this approach is that each space has its own namespace, so pages created within the space are unique, and their names cannot clash with pages from other spaces. Therefore, instead of prefixing all pages with the project name, such as "DM-123 Use Cases" or "DM-123 Systems", it is possible to have sections "Use Cases" and "Systems" in each project which is more convenient. Whatsmore, space could have its own color :-)

The decision is up to you. But beware that if you choose to create separate project spaces, don't forget to create a page under the Project and Changes space and link to the project space from there. This will ensure that all projects will be accessible from one place despite being stored in multiple spaces.