Effective Analysis and Documentation

Effective Documentation Practices Implemented

This chapter demonstrates how employing Confluence together with the middleware supports the general Effective Analysis practices.

Accessibility

Documentation should be public and easy to access (11). Confluence is a web application, accessible through a web browser, so it allows anyone to access it without installing any additional software. We also believe that anyone in the company should be able to edit the knowledge base so that the imperfections could be corrected instantly.

  1. The knowledge base is accessible from one place
  2. The knowledge base is accessible by anyone with the permission
  3. The knowledge base could be modified by anyone, or anyone could at least propose a change by leaving a comment

Unique Ids

Each Confluence page has a unique page id, and since there cannot be two pages with the same name within the space, each page also has a unique URL. This allows sharing and referencing specifications via the link.

Unification

One of the core Effective Documentation requirements is a unified form (10) of the produced outputs. It means that in an ideal world, the wiki pages documenting two different systems should look very alike. Ideally, they should give the impression they have been created by a single person. This is not easy to achieve, but with the help of middleware, the documentation consistency could be improved a lot.

1. Unified page title format
Since page titles are generated automatically by the middleware, it is easy to ensure that all documentation pages have titles constructed according to the single pattern

2. Artifacts Templates
If the documentation is composed of fixed artifacts, the middleware can create a skeleton page for each new artifact

Traceability

Interconnecting pages with hyperlinks is the core Confluence functionality. It can list incoming links or automatically detect dead links, but it is not what we call tracing. When we are talking about tracing, we do not mean connections between pages but connections between elements in the repository. This means that listing system modules, for example, should not be created manually or using links between Confluence pages but should be automatically generated by middleware based on the relationships stored in Enterprise Architect.

Diagrams

Besides maintaining relationships between artifacts, the other big pain related to documenting using the word processor is including and updating diagrams. Every time a diagram is modified in Enterprise Architect, it needs to be exported and updated in all documents. The more convenient way is to document in Confluence and let the middleware to automatically update the diagrams.