CASE + Wiki

In the previous chapter, we stated why we are not fans of storing documentation in the separated word processor documents, despite it is still a common approach among companies. For this reason, we will focus just on the two remaining options: storing documentation in the CASE and in the enterprise wiki software.

CASE

(+) Pros

• Each artifact is a unique object stored in the database
• Relationships between objects are also stored in the database (useful for analyzing impacts of changes)
• Models do not own the contained elements - elements are only referenced which allows reusing them instead of duplicating
• Everything is stored in one place
• Searching is fast due to the underlying database
• Objects can be exported as a data file
• It is possible to automatically generate textual documentation from the repository. As a result, multiple outputs could be generated without duplicating information as all outputs come from the same data source.

(-) Cons

• CASE tools lack the advanced text editing features of word processors, such as rich text formatting, inserting attachments, or revisions. This is very limiting for analysts.
• Generating textual outputs from the repository is possible but not straightforward. It requires somebody with the skill to create and maintain the templates.
• The specification generated from the CASE is basically just a good old offline document with all the negatives mentioned in the previous chapter
• Because CASE tools are strong in modeling, yet weak in textual descriptions, analysts using just the CASE tools tend to prefer creating a model even in cases when a couple of sentences would be sufficient. This is wasting time.

Wiki

(+) Pros

• Advanced text editing and formatting features
• Supports collective ownership and collaboration
  • Easily accessible to anybody with permission
  • Easy to learn, simple to use
  • Sharing is straightforward
• Includes versioning and changelog
• Access management - possible to restrict access to certain parts
• Global searching feature
• Flexible documentation structure

(-) Cons

• Documentation is text-based - it is not possible to manage relationships between artifacts or export the data
• Updating diagrams
  • Every time a diagram is changed, it needs to be exported and updated in all pages
  • This is often solved by using plugins to draw diagrams directly in the wiki, but this approach will not work for models created in the CASE tool

Hybrid Approach

The previous comparison shows that selecting either approach comes with significant disadvantages, as each method excels only in a specific area. But what if they could be combined so that the advantages would remain and the disadvantages would vanish? This could be possible if each tool was used only to do what it was designed for: CASE for modeling, wiki for documenting and collaboration. The resulting hybrid approach will then have the following characteristics:

1. Agility
   • Easy to access by anyone, no software installation needed
2. Collaboration
   • Anyone can edit the documentation, editing is intuitive
   • Sharing via links
3. Advanced text formatting
   • Headings, images, tables, hyperlinks etc.
4. Documentation management
   • Versioning, changelog
   • Searching
   • Notifications
   • Comments
5. Unified knowledge base
   • All information stored in one place
   • Unified look and feel achieved by using predefined templates
6. All artifacts stored in a single repository
   • All artifacts are stored as unique objects in the database together with their relationships
   • It is easy to search objects, export them in various data formats and track relationships between them
7. Modeling
   • Ability to visually model various organizational components
   • The result is not just drawings, but models which reuse objects from the repository
8. Automation
   • Automatic update of diagrams
   • Automatic documentation format check
   • Automatic corrections

Middleware

Combining CASE with wiki supports the advantages of both approaches and suppresses the disadvantages. However, separating the data (CASE repository) from its documentation (wiki pages) comes with a major imperfection. Since each artifact has basically two representations, they must be synchronized:

If artifact or relationship is changed in the repository, its documentation in wiki becomes outdated and must be synchronized. To remain effective, these repetitive "corrections" must be automated to avoid the hassle of changing everything in two places manually. This means introducing a "man in the middle" - a software doing the routine synchronization work:

Such architecture allows combining the two worlds and taking advantage of both of them. On the one hand, there is a repository of artifacts and their relationships, which is easy to manage, allows searching, exporting, modeling, and performing "database-like" queries. On the other hand, textual specifications are managed in the modern enterprise wiki software which offers rich text editing features and advanced documentation management capabilities: