Monday, October 30, 2006

Wiki for a software architecture document

Wikipedia has revolutionized the way information is generated, edited, and made accessible to various Internet audiences. Wikipedia, a publicly edited encyclopedia, is based on a concept of wiki where any user can edit any information at any time. This ad hoc approach sounds like a bad idea, but it may be useful for designing and documenting software architecture – democratically. The primary goal of the wiki solution is to make the system’s software architecture document a living document so that it can accessed and used effectively by all system stakeholders.

Compared with the industry’s “standard” approach to documenting software architectures (advanced word processor [MS Word], drawing software [Visio], and source control [CVS]) the wiki approach provides the following benefits. The document is accessible via any web browser, transclusion allows for repetition of information defined earlier in a document, source control and mechanism for merging & discussing changes are built-in. The wiki approach, however, suffers from lack of built-in image editing functionality. This means frequent copying and pasting from another image editor, which may or may not be available to all wiki user base.

The wiki approach is also a paradigm shift to managing software architecture. In an ordinary hierarchical organization software architecture design is done by a single person or by a very small group of software architects. The wiki approach levels the hierarchy and allows any team member to make changes. From one point of view the allocation of ownership may empower team members to contribute, but on the other side not a single person is accountable for the whole design. This may pose a challenge to a more traditional accountability structures and to people with fragile egos.

A technical note (TN) released by the Software Engineering Institute (SEI) shares the experience of using a wiki web-based tool by a small team of software engineers while working on a project for the Siemens corporation. For a more detailed discussion please see the TN page or TN in PDF.

Thursday, October 26, 2006

Deployment view: documenting the essence of the target environment

Sufficiently documenting software design, including source code, is essential. But sufficiently documenting fundamental software architecture views is critical. There are many views to consider during design and analysis of a system. This time a basic deployment view is discussed.

A simplified deployment view is a high level tangible mapping between system elements (e.g. messaging queue) and physical hardware spread across network topography.

One of colleagues, PJ, observed the following situation at his current client engagement.

The task of overseeing the deployment of a significant iterative release into the test environment was assigned to the associate architect of a system. The client’s environment features institutionalized configuration management policies that can be circumvented when pushed, but the deployment manager has no access the system directly. The test environment administrator, who physically controls the test environment, is only available by phone and email.

The build and deployment process went smoothly across most of the tiers of the test environment with the exception of the application tier. Specifically the configuration of the messaging framework and the business logic residing in this tier was not deployed successfully.

Having no access to the environment where an unstable release is being deployed is challenging. What made this situation dire is lack of usable deployment documentation. Yes, there were some back and forth emails containing information about various machines across environments, but none of the information could be readily used as a reference. This ultimately resulted in the following fundamental problem: people involved in the process of configuring and troubleshooting the environment did not have a shared view of the solution. The deployment timeframe stretched from that afternoon to late evening and then extended onto the next few days and eventually weeks until full smoke test could be run.

In an ad hoc environment, no matter how big or small, it is the responsibility of the architect to always have a readily available deployment view in the back of his pocket.

Software architects and designers may feel lax when it comes to recording decisions on the daily basis: a conscious and a well thought design may materialize with little documentation overtime. Not surprisingly the deployment view is the last thing that comes to mind in a deadline oriented ad hoc environment. But it’s the deployment view that represents architect’s view of a target environment and lubricates communication channels between the design and development team and the colleagues who manage the test environment. Like a fire escape plan on the door of a hotel room a basic deployment view must show the components of a system being deployed specific to the target environment.

Tuesday, October 03, 2006

This blog: what's in it for you?

The motive behind this blog is to expose the human aspects of the software architecture discipline and how they fit into the overall software development process. Due to purposeful omission of technology specific details the blog targets programmers, developers, project managers, students, interns, junior and seasoned software architects alike.

Some of the observations and conclusions may seem obvious and familiar as they have been documented in classical software engineering books such as Fred P. Brooks’s The Mythical Man-Month: Essays on Software Engineering, Roger S. Pressman’s Software Engineering: A Practitioner’s Approach, and Ian Sommerville’s Software Engineering. Further, some of the problems & solutions may not seem to be architectural in nature at all. That’s precisely the point. The goal of the prose is to expose the obvious and to prod the reader to ask oneself if a given scenario or a point of view is applicable to own situation. If just one reader sees personal value in pursuing a solution, or asking subsequent questions, then the objective of the blog post has been fulfilled.

The architecture of a software system is only as good as its implementation. In a fictional world an architect may pause the time and retreat from the real world to come up with the perfect architecture. The software engineering world in the trenches is far from that. A practicing architect is subject to tangible forces such as budgets, schedules, resources, and intangible forces such as “the bus problem” and politics. It is our hope that through concrete solutions and through philosophical discussion the reader will have appropriate ammunition tackle the problems are relevant to his or her role in the software development lifecycle.

Sunday, October 01, 2006

What is firebrand?


“The firebrand is the person who recognizes what is natural, what is organic, what is alive and vital in life, the person who dares to live, to be, and to create, often in the face of interference, rejection, deceit, and betrayal. The firebrand is a burning ember, life that is in each of us and that provides the spark and energy to speak against what distorts, hides, and denies our being and truth. It is that which awakens within us, when we must declare our independence or when we discover a new formula for living. It is the path that enables us to participate in the mystery of creation, uniquely and individually. The firebrand expresses her- or himself in two basic ways: as the torch that lights up the darkness, and the as the carrier of the torch, throwing light into the darkness, and often disturbing complacency and brewing trouble. Being a firebrand is a way of raising temperatures and creating conflict, turbulence, and dissension.

The motive of the firebrand is not to attack or destroy others but to bring to light a basic truth, to take a stand, and to declare and own who one is, especially in the face of perceived violations of one’s values and rights and interferences with one’s goals, purposes, and meanings.

In relation to one’s self, the firebrand engages in reflection and self-dialogue that evokes awareness of ideas, projects, and goals, insights, into one’s deviance from others, and particularly from the mainstream people. The firebrand chooses to be different when being different represents a truth, when being different guides the fulfillment of basic human values and actualization of one’s potentials.

In relation to others, the firebrand seeks to maintain what is unique and distinctive, what will enrich a relationship and keep it alive in fundamental ways. The firebrand avoids roles, categories, classifications, hierarchies, fixed routines, and practices but rather seeks to create rituals, searches for new rhythms and connections with others, keeps secrets and confidences, and engages in conflicts and intimacies when these are true to experience, when these are ways of enhancing life. The firebrand is concerned with being open, honest, adventurous, and creative. If none of these processes are viable, the firebrand terminates the activity or relationship and moves on.”

- Moustakas, Clark. (1995). “Being-In, Being-For, Being-With” pp. 5-6.

Blockchain learning path for Enterprise Software colleagues

I wrote this post to document my learning path of blockchain concepts and Ethereum technologies while keeping my “new to blockchain” collea...