Tag Archives: software-architecture-document

IBM Doors Next Generation: Are diagrams a gateway for new modelers?

Sometimes engineering methods fail because they are not understood or too hard to try and integrate into established habits.   In my experience, Model Based Engineering approaches sometimes never take off because of these types of ‘barrier to entry’ problems.    In this post I want to share how IBM’s Doors Next Generation may be onto something with their integrated support for ‘diagrams.’

Typical Scenario

A scenario I have experienced multiple times is a team or group already has their established tool chain, and there is little time, room, expertise or interest in adding yet another tool to the mix.

Now, if one of these tools already supports a Model Based Engineering approach, then you are done.  Start modeling.

Which leaves you with two typical routes:

  1. Use another tool for modeling, or
  2. Use another tool for diagraming (e.g. Visio, PowerPoint)

And the majority of my experiences involve an optional, diagraming approach.

Doors Next Generation & Diagrams

So why not just bring the diagram into the Lifecycle Management web client?  Aside: And I am using Lifecycle Management to represent Product Lifecycle, Collaboration Lifecycle or Application Lifecycle Management.

This is what IBM Rational DOORS Next Generation (DNG) did. Take a look.

A colleague recently gave me a DNG demo, which showed the diagramming approach has aspects of the UML notation and may support having a model library of sorts.  But I suspect this is more of a ‘diagram’ than a ‘model.’

But, does it matter?  If many times people turn to an additional hoop to jump through only to model something that is disconnected from the rest of the Lifecycle Management, why not work with a diagram that is integrated with the Lifecycle Management tool chain?

Beyond Diagrams

As I understand it, IBM has an offering to those who want to take a Model-Based-Engineering or Model-Driven-Engineering approach.  So in some ways DNG with Diagrams can be a stepping stone towards a true model based approach.

I have yet to get some hands on with the tool chain, but IBM Rational Software Architect is the UML based modeling solution.  And there is a way for this to integrate with DNG.

Implication: Start with IBM’s RTC Platform

Basically this means you are using at least IBM’s DNG offering.  Just wanted to be clear, there is no real magic.

The potentially naturally is that you could (1) transition to the suite of offerings from IBM or (2) take an OSLC based approach and link or sync your Lifecycle Management tool with IBM’s via its jazz.net OSLC compliant framework.

Concept: From Microsoft Office to IBM Rationale

What came to mind is exactly what IBM uses to advertise & advocate for DNG being superior to office applications for Lifecycle Management and Requirements Management.

Summary

A primer to IBM’s Lifecycle Management offerings of a lightweight and integrated diagramming approach and its heavier weight modeling offering.

 

Tried any of these?   What are your experiences?

Conceptual design of implementing a Software Architecture Document with Atlassian Confluence

Overview

This blog post showcases a conceptual design for implementing a Software Architecture Document (SAD) in a Atlassian Confluence Wiki.

Purpose

Share the design concept to a broad audience by publishing online.

Scope

Defines the initial steps for creating Atlassian Confluence (will be referenced as Confluence from here forward) wiki pages aligned with the SAD example provided by the Software Engineering Institute (SEI).

Background

I was working on a project which was getting into a documentation problem.   I wanted to know the common practices in industry and started researching documentation practices for software architecture and systems.  The research led to the ISO/IEC 42010 standard, SEI’s contribution to the topic and the related Documenting Software Architectures: Views and Beyond book on the same topic.

In the specific project I was working on, the direction was to use Confluence for documentation.  While I had been regularly publishing to the wiki and benefiting from using the Macro and Template features, I wanted to dive  deeper into what Confluence had to offer to understand how the concepts of the SAD can be applied to the wiki to provide a documentation solution requiring a reasonable effort to maintain and scale.

Design Description

Overview

The flow is for the publishers of the documentation to start with the SAD Microsoft Word template, import the template into Confluence, create Confluence Template Pages, and add sections to Confluence using Confluence Templates as the architecture changes over time.

Implementation

The remaining parts of this section describes the implementation in more detail.

Initialization and Addition of pages

The intended flow is as follows:

  1. Publishers download the SAD Microsoft Word template,
  2. Publishers edit SAD template and save
  3. Publishers import SAD document into wiki
  4. Publishers add Viewpoint Definitions, Views and View Packets using Templates.

Template Design and Macro Usage

This section provides a structural view of the wiki modules used in the design.

The UML Class Diagram below shows the templates and macros used in this design.

Class Diagram
Class Diagram

 

The UML Object Diagram below shows the pages that would exist for a scenario where there are two Views, each View having two View Packets.

Object Diagram
Object Diagram