Versioning

The entire documentation approach presented in the previous chapters works very well when the goal is to implement a new solution without changing any existing organizational components. The newly created solution is not yet used by anyone, so it can be modeled relatively independently in the working EA repository, eliminating the need to deal with conflicting versions. After the system is released, the selected elements are exported from the working repository to the documentation repository, and the solution officially becomes part of the enterprise knowledge base:

The same applies to wiki pages, which represent the solution artifact specifications. During analysis and development, solution components are documented using "project" wiki pages whose purpose is to provide just enough information for a successful implementation of the solution. However, the project documentation of an artifact often differs from the final post-release documentation, as the needs for development documentation and post-release documentation are different. For that reason, after exporting the new artifacts to the documentation EA repository, corresponding "documentation" wiki pages must be created for these artifacts. They can be created manually from scratch or automatically by middleware as copies of the project pages.

1. Creating Post-release Documentation

Documenting solutions that have already been deployed to production is easy because the solution is fixed, so it will likely not change during the documentation process. It also means that there is no need to worry about documentation versioning, as there is always only one as-is version. Each artifact is then represented by a single element in the EA documentation repository and is described by a wiki page in the as-is knowledge base.

To ensure documentation consistency, elements cannot be created directly in the documentation repository. Instead, they should always be created in the working repository and subsequently transferred to the documentation repository. Furthermore, it is not possible to create a documentation wiki page from the working repository, ensuring that the documentation page is not created until the corresponding element exists in the documentation repository.

2. Documenting Development Artifacts

It is straightforward to document existing solutions since they are stable. The situation gets complicated when a solution changes already existing components.

Since the working repository is just a mirror of the as-is documentation repository, once the solution is deployed to production, the changes can be easily exported to the documentation repository. For example, if a new data item needs to be added to an existing data file, it is enough to simply modify the corresponding element in the working repository. As soon as the change is deployed, the updated element is transferred to the documentation repository (based on its GUID) so that the documentation repository is in sync with the deployed state. The same approach applies when a new element, or a part of it (attribute, operation, etc.), needs to be added. This works for diagrams as well. The only case where caution is required is when deleting elements, as they might be used in diagrams or connected to other elements. Before performing a delete, we recommend finding all usages in diagrams (Ctrl+U) and checking all relationships using Traceability.

However, this elegant approach comes at a price. First, you need to keep a record of the changes you have made so you know which elements need to be transferred to the documentation repository. This can be solved by creating a connection between the modified element and the element representing the project (which is recommended anyway, as it helps track changes made within that particular project). This approach is demonstrated in the following picture:

Second, since all artifact changes are made to a single element, it is only possible to model one change at a time. As a result, this approach does not work well when multiple versions of the same artifact need to be modeled. It is not recommended to create a separate element for each future version—the working repository should remain one-dimensional, meaning only one future version of an element can exist at a time. To maintain simplicity while supporting multiple versions of elements, the only viable option is to mark changes visually—for example, by coloring version 1 red and version 2 green, or by specifying the changes using text.

This issue is demonstrated in the following picture. There are three changes to be made to the Customers Interface, yet they will be deployed in separate releases. Since there is only one element representing the to-be version, all future modifications must be modeled directly within the existing interface—in this case, in text form:

Modeling artifact changes is pretty straightforward with this simplified approach, as is introducing new artifacts. A new element can be created either in the "project" package or directly in the package from which it will be transferred to the documentation repository. The latter is easier because the elements will simply be exported to the documentation repository from where they already are. The downside is that elements remain scattered across the entire working repository until they are synchronized with the documentation repository. On the other hand, keeping new elements in a separate project package keeps all new items together in one place, though they must be moved to their final destination after the solution is released.