Versioning

The whole documentation approach presented in the previous chapters works very well when the goal is to implement a new solution without changing any existing organizational component. The newly created solution is not yet used by anybody, so it could be modeled relatively independently in the working EA repository, and there is no need to deal with colliding 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 knowledgebase:

The same applies to the wiki pages, which represent the solution artifacts specifications. During analysis and development, solution components are documented using "project" wiki pages whose purpose is to provide just enough information for the successful implementation of the solution. But the project documentation of the artifact often differs from the final post-release documentation as the needs of the development documentation and the 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 could 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 probably not change during the documentation process. It also means that it is not necessary to care about versioning of the documentation 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 the consistency of the documentation, it is not possible to create elements directly in the documentation repository. Instead, they should always be created in the working repository and subsequently transferred to the documentation repository. Next, it is not possible to create a documentation wiki page from the working repository to ensure 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 the solution is changing 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 could be easily exported to the documentation repository. For example, if a new data item is to be added to an existing data file, it is enough to just modify the corresponding element in the working repository accordingly. As soon as the change is deployed, the updated element is transferred to the documentation repository (based on its GUID) so the documentation repository is in sync with the deployed state. The same approach is applicable when a new element, or its part (attribute, operation, etc.), needs to be added. It will work for diagrams too. The only case when it is worth being careful is deleting elements as they might be used in diagrams or could be connected to other elements. Before performing the delete, we recommend to find all usages in diagrams (Ctrl+U) and to check all relationships using Traceability.

However, this elegant approach comes at a price. First, you need to keep a record of changes you have made so that you know which elements need to be transferred to the documentation repository. This might 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 the particular project). This approach is demonstrated in the following picture:

Second, since all artifact changes are made to a single element, it is possible to model only one change at a time. As a result, this approach does not work well in cases when it is needed to model multiple versions of the same artifact. It is not recommended to create a separate element for each future version - the working repository should remain one-dimensional, so only one future version of the element could exist. To keep the simplicity and to support multiple versions of the elements, the only possible way is to mark the changes visually - for example, colour the version 1 with red and version 2 with green, or specify the changes with text.

This issue is demonstrated in the following picture. There are three changes to be done in 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 in the existing interface - in this case in text form:

Modeling artifacts changes is pretty straightforward in this simplified approach, and so it is introducing new artifacts. The new element could 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 be simply exported to the documentation repository from where they are. The downside is the elements are scattered around the whole working repository until they are synchronized to the documentation repository. On the other hand, keeping the new elements in a separate project package keeps all new items together in one place, yet they need to be moved to the final destination after the solution is released.