Confluence
Confluence represents a convenient way to store information in a textual form. In the Effective Analysis, it serves as a counterpart to the model-oriented Enterprise Architect.
Documenting Using Pages
In Confluence, everything is a page. There are no folders or packages which would form the structure of the repository. Instead, each page is placed under its parent page, so the structure is pure page-based. The only tool that helps organize pages are spaces, which are basically containers, grouping pages that are logically related.
In Effective Analysis, a Confluence page may describe two different things. First, it could be a specification of a concrete artifact that is represented by an element stored in Enterprise Architect. This specification is generated automatically by the middleware software according to a predefined template:
The other type of specification is a general "document", such as an overview, BRD, or a system specification. It is the type of document which used to be typically created in Word, but nothing is preventing us from starting to create them in Confluence as well. Not only could the author use the collaboration features of the wiki software, but storing these documents in one repository along with the artifacts allows us to refer to each other, which makes it easy to navigate from the general concepts to the details. Additionally, it is possible to generate some parts automatically by the middleware, which prevents duplicating information and makes it easier to keep the documents up to date.
Name Spaces
Confluence is designed in the way that it does not allow to create multiple pages with the same name within a single space. For this reason, we prefix all pages with the artifact abbreviation, as you can see in the example above. However, besides solving the possible page name collisions, the prefixes also help to find the right page faster. There could be a use case called "Create Customer", a screen "Create Customer" and a function "Create Customer". Searching for "Create Customer" would return many results, but searching for "UC Create Customer" will find the expected page immediately.
Confluence Effectivity Tips
- Press 'e' to start editing the page
- Press "Ctrl+S" to save the page (doesn't work when standing with the cursor on the page title)
- While editing the page, press "[" to insert a link to another page
- To link to a recent page, choose Link > Recently viewed and select page from the list
- To set space homepage: Space tools > Overview > Edit Space Details > Home page
- Locate page by its path
- Most of the artifact templates contains the "Repository path", which describes wherein the repository structure the artifact is located. However, EA does not provide an easy way to locate the element by this path, so we have to use the EA Navigator extension again, namely its "To FQN" feature. Just copy the generated "Repository Path" to the clipboard and choose "To FQN". The add-in will then find the item which matches the path in the clipboard and selects it in the project browser.
- Most of the artifact templates contains the "Repository path", which describes wherein the repository structure the artifact is located. However, EA does not provide an easy way to locate the element by this path, so we have to use the EA Navigator extension again, namely its "To FQN" feature. Just copy the generated "Repository Path" to the clipboard and choose "To FQN". The add-in will then find the item which matches the path in the clipboard and selects it in the project browser.