Wednesday, February 11, 2009

Documenting Software Architecture

Software architecture has been around as a discipline for four decades. The discipline emphasizes on the structure of software systems and getting the structure right. The discipline came into the limelight in the 1990’s when complex, large-sized IT projects started becoming increasingly popular and commonplace. The popularity saw the emergence of various different schools of thought that doctrinated different views towards software architecture and popularized them through their adherence in real world projects. With the growing number of variations and views towards software architectures, IT practitioners, typically, feel the confusion on which school of thought to believe in.

However, the toughest challenge to software architects comes in the form of finding the Holy Grail on how to document a system or application’s software architecture. Documenting software architecture is as much a science as it is an art form. While the science lies in the proper analysis, understanding and the usage of the proper description language to define the software architecture of the system, the art form assumes significance when a clear, crisp, non-redundant depiction is required.

Software architectures require a very crisp and clear documentation to communicate the developing solution to the business and IT stakeholders. Many IT projects have bitten the dust owing to lack of clarity in the documented architecture artefacts. This lack of clarity introduces a gap between the system’s architecture and the downstream design and implementation artefacts – deviation is inevitable.

Software architects find it immensely challenging to determine how to document software architecture in a way that clearly articulates the solution. While over engineering and excessive documentation adds significant delays and associated risks to project delivery, sub optimal documentation results in a serious lack of the developer’s understanding of the solution architecture – which is expected to define the constraints within which the technology should to be leveraged to develop the code.

What if I come up with a book on this topic? Would you read it? What would you like to see covered in the book? Your wishes may be granted - just speak them out for me!


Anonymous said...

Hello Mitra,

First of all, I'd like to say thanks to your series of Documenting Software Architecture on IBM developWorks. They are very useful. However, my problem is that I couldn't find out the series 5 for Operational Architecture & series 6 for Architecture Decisions. If you had, could you please to share with me? Thanks much!
Huan Nguyen

Tilak said...

You are correct in that the rest of the series was not published. The reason for that is somewhat intentional. I kept getting a very large amount of emails from people who were waiting for the rest of the series and some of them even said that there project is waiting for the series to get published so that they can proceed!

I have contemplated to author a book on this subject which will be primarily encouraged by the reviews my article series have been getting. I am hoping to start working on the same shortly. Maybe you have to wait a little bit more and you will certainly be positioned with much more practical information!

In the meantime, if you or your company needs any specific consulting needs, I'd be happy to assist.

Anonymous said...

It's great to hear that you're planning to have a book in this area. I'm waiting for you.... :D

Anyway, I'm looking for a software architecture template that nearly maps to your recommendation. So could you help to share a SAD sample if it's not confidential?

Thanks in advance,
Huan Nguyen

Tilak said...

To be honest there is no software architecture template or document that captures all my practical recommendations into one document. That is just not possible.

In fact, an architecture is finally manifested as a set of work products that collectively define the architecture through a set of multiple views or viewpoints each addressing a specific aspect of the architecture domain.

For example, the articles in my series; each one of them will be an instantiation of a template that addresses that specific aspect of architecture. So there is no one size fits all.

The actual creations I have are unfortunately all from client engagements and hence I am bound by NDA regulations.

Why dont you advise your organization to conduct a workshop or a small project the output of which is specifically what you have in mind? That way, you can create that elusive set of templates and use them for all subsequent projects!
I would be glad to help in that context.

tay said...

I'm looking for a company that has implemented service-oriented architecture. I have a lot of questions. I want to ask them for experts working in that company. Questions are as follows.

Case study questions


1. Company name:

2. Working position:

3. Duration of employment at the company:

4. Do you want your answers to be treated confidentially?

a. Yes

b. No

5. Has your company succeeded conducting migration from legacy system to SOA?

a. Succeed

b. Failed

c. Still in progress

6. When did the company adopt SOA?

7. Can you provide a short description of the company SOA environment?

8. Why did the company decide to deploy SOA?

a. What benefits did the company expect to attain?

9. What role has each of the following people played in the implementation and success of the SOA


a. CEO

b. Project manager

c. Programmer

d. System Architect

e. Other party, which are ….

General Questions:

1. How successful have SOA adoption projects been in terms of migrating LS into SOA? How far has the

SOA adoption project been successful in terms of its promised benefits? (In terms of reusability, agility,

efficiency, productivity, etc.)

2. What organizational / technical factors contributed to migration of legacy system to SOA adoption

success / caused SOA adoption failure in your company? Explain and prioritize each.

3. Please explain and prioritize the following factors and their roles in your experience of migrating legacy

systems to SOA.

a. Potential of legacy system

b. Strategy of migration

c. Governance of SOA

d. Business process of the company

e. Budget of conducting migration

4. How close have you and your team been monitoring the project progress and outcome? Have there been

any signs of early failure or success in your monitored progress? What were the reasons?

5. What challenges did you have to face technically when migrating to SOA architecture? (In terms of

Application development, infrastructure development, data transformation, etc.)

tay said...


Technology Perspective:

Factor: Potential of Legacy System

6. How far did you consider the potential of legacy system in the migration process? Did you use most of

the components of legacy systems in the system using SOA?

7. How do you measure the feasibility of converting a set of components in legacy system to SOA?

8. How far did you consider the architecture of the legacy system? Does it increase or decrease the

difficulty of the migration effort?

9. How far has dependence of legacy system on commercial products (product license, etc.) affected the

migration of legacy system to SOA?

10. Do you consider the quality of service (in terms of performance, reliability, security, etc.) as a success

factor when conducting the migration process?

11. How far did you estimate the cost, difficulties and risk when measuring the potential of legacy system

for being reused in SOA?

12. What important role did the following characteristics of the legacy systems play in the suitability of the

legacy systems for being migrated into SOA? ( Prioritize them from 1(most important) to 8(least

important) and cross out (×) the ones you do not consider as important at all)

a. Size and Complexity

b. Level of documentation

c. Scale of changes required

d. Support software required

e. Reusability factors

f. Service Abstraction

g. Service discoverability

h. Code Quality

Factor: SOA Governance

13. What factors have you considered in your SLAs (Service-Level Agreement)? (Do you have an SLA?)

Factor: Strategy of Migration

14. What migration strategy/ technique did you choose? Why?

Business perspective:

Factor: Business Process

15. How dependent was the business process of the company on the IS legacy architecture?

16. How far have you considered the requirements from potential service users?

Factor: Budgeting

17. How far has initial budgeting affected success in migration of legacy system to SOA?

18. Can you provide us with some estimation of the total costs in terms of both human resources and

monetary expenses the project implementation has had for the company compare to pre project


Thank you for your time and participation in our research study!

If there is any further questions would arise, is it okay if we get back to you with the questions?

Before publishing the final essay, you will get the opportunity to review our interview summary, and correct

possible misinterpretations if any.