http://www.computer.org/ses11

June 6: Social Day

June 7-8: Board Meeting

In June 2009, the Software Architecture Challenges in the 21st Century Workshop sponsored by IEEE Software, University of Southern California, and University of California Irvine attracted quite a bit of interest. Pekka Abrahamsson, Philippe Kruchten, and Grady Booch all addressed the role of software architecture and architecting in agile software development. I ended up writing an editorial based on the Kruchten and Booch talks for the September/October 2009 issue of IEEE Software.  The editorial is also featured in the August 2009 edition of Computing Now.

In that editorial I explore the common themes raised by Booch and Kruchten, and also touch upon where the two gurus differ. The common themes I identified are:

• The scope of software architecture
• Architecture-phobia
• Architecture’s omnipresence
• Architecture for self-governance
• Architecting as a continuous activity
• Just-enough architectural representation

These themes made me reflect on my former views on the topic of how agile and architecture interact. Those views were expressed in a tongue-in-check article that I had written for Agile Times back in 2003 .  The article was sarcastically titled “Let’s Scale Agile Up”. In those relatively early days of agile, I used to advocate a purist agilista approach that downplays architecture. I used to object to any attempts to scale up agile software development by augmenting it with explicit architecting. I was wrong. I realized how wrong I was in a recent project.

The project was small, but I couldn’t crack it with seat-of-the-pants, “let the design emerge” attitude. The project’s success relied on the ability of a complex core technology to solve the problem at hand. We had to nail down technical decisions at the beginning. And these decisions couldn’t be reversed easily later, even though the project was small.  My client demanded to know about the main components, how they would interface with each other and be integrated with the core technology, how they would be decoupled from each other for maintainability and extensibility,  and what general functionality they would provide. He wanted me to document the underlying decisions. In a nutshell, he demanded that I do some architecting.

I ended up spending a week and a half on these issues, constantly soliciting clarifications from my clients on the requirements, running endless spikes to resolve technical risks pertaining to the core technology, and coming up with a general design in the process. And I am glad my client insisted because this upfront activity paid off.  It turned out that seemingly subtle aspects of the requirements had an impact on how the core technology, a hairy rule engine, would work to solve my client’s problem. Interestingly, I no longer associated all this early activity, as I did back in 2003, with the “grit” between the gears, the grit that contaminates the project and brings it to a screeching halt.  That grit did not interfere with planning and running the project as a highly incremental and iterative one. Actually, it turned out to be a lubricant rather than a contaminant. I grew up, I suppose.

Number 10. Ignore reviewer feedback.

Number 9. Stick to clichés.

Number 8. Borrow without giving due credit.

Number 7. Don’t worry about the language.

Number 6. Ignore your work’s limitations.

Number 5. Ignore the context and prior art.

Number 4. Rely on argumentation to push an idea.

Number 3. Ignore your audience.

Number 2. Be undeservedly authoritative.

Number 1. Write in a purely descriptive style.

In this post, I’ll address the top five sins from Number 5 Number 1.  

Sin #5 is the sin of laziness, or the appearance of it. Readers want to know what encompasses an idea, a piece of research, or a narrative about an interesting experience. They want to be able to position it relative to other works that are similar. They want to know about the connections between concepts, the progression of ideas. They want to understand the context. Prior art and context provide the beginning of a story. Without the beginning, the story struggles to survive. Without prior art and context, a paper has little value.

Sin #4 is the sin of defensiveness. Relying on winding questionable arguments to push an idea makes it seem like the author’s premise doesn’t hold water, as if the weakness of the idea needs to be hidden behind a veil of twisted logic. A better alternative to using argumentation is presenting facts and existing evidence. If evidence is not strong, just admit it. No apologies are necessary.

Sin #3 is making no attempt to differentiate among the various types of audiences. If you write up your excellent research in an overly scholarly style for a professional magazine, it will bounce back. If you write up your exceptionally insightful project experience report in an overly colloquial style for a research journal, it will bounce back. Style matters to your target audience. In addition, certain elements need to be in place in different types of publications at varying degrees. A comprehensive, academic-quality literature survey may not be necessary, or even overkill,  for a magazine, but is essential for an archival periodical. Know your audience, and know what each type of publication requires to meet its audience’s expectations.

Sin #2 often accompanies Sin #4. It comes from the absolute tone that authors often use when expressing what is simply a point a view. Or, it comes from the tendency to pepper an article with unsupportable statements or embellish ideas with virtuous qualifiers and superlatives. This almost always makes reviewers recoil with disgust and fury. Avoid being unnecessarily absolute and self-assured. Humility, without being deliberately fuzzy, will work better than you think. However, it doesn’t imply that you shouldn’t take risks. Your message can still be provocative.

Perhaps the best strategy to use to get a paper rejected is to take a good idea and just write it up. And stop there. This brings us to Sin #1. A purely descriptive style is one in which you just describe something — whether it’s a concept, a process, an idea, a new technology, an experience, a study — in gory detail, definition by definition, step by step. You start from the beginning, explain all the elements in a clear, natural sequence, perhaps give a few small examples, and then you’ve done your job. You can stop. What could be wrong with this straightforward approach? Nothing. It may be perfectly OK for a white paper, a chapter of a text book, an appendix, a manual, a handbook, or a technical report. But it won’t make very interesting reading and it certainly will not buy you any brownie points with the reviewers. Try it!

Releated resources:

• Tips for Software Authors
• How to Write a Good Technical Article

My IEEE Software column on the topic is also featured (Cloud Computing: Does Nirvana Hide Behind the Nebula?) …

My top-10 list, which applies to both research and practice pieces,  goes like this:

Number 10. Ignore reviewer feedback.

Number 9. Stick to clichés.

Number 8. Borrow without giving due credit.

Number 7. Don’t worry about the language.

Number 6. Ignore your work’s limitations.

Number 5. Ignore the context and prior art.

Number 4. Rely on argumentation to push an idea.

Number 3. Ignore your audience.

Number 2. Be undeservedly authoritative.

Number 1. Write in a purely descriptive style.

In this post, I’ll address the bottom five sins from Number 10 Number 6. I will tackle to top five in a subsequent post. So stay tuned.

If you’ve already gone through the process of submitting a paper to a peer-reviewed publication like IEEE Software,  you know that once the submission has been screened in by the editors, it goes through at least one round of peer reviews followed by author revisions. Often, two such rounds are required. Sin Number 10 applies to a submission that has already survived a round of peer reviews, and the editors are now recommending revisions to address the reviewers’ comments.  And you’re naturally apprehensive: the pesky reviewers don’t understand your work. How dare them? You decide to just pay lip service to their objections and perform some cosmetic changes to silence them, thinking that the submission has already been vested and rejection in a subsequent stage is unlikely. But rejection is unlikely only if the reviewers and editors give in, or overlook the superficial nature of the revisions you are comtemplating. Albeit reviewers and editors are quite diligent, and they won’t let go. Editors, as per editorial policies,  are not at liberty to ignore reviewers’ concerns although they have plenty of discretion. Indeed, it’s more common than authors think to have a submission rejected following a round of revisions. And sometimes an article gets rejected even after several rounds. The better strategy requires a different author perspective, one that is not defensive. An honest attempt to address and reconcile reviewers’ concerns almost always pays off. Think of the reviewers as a sampling of the readership: some may not be as familiar as the area as you would like them to be, and others may carry biases, just like your readers. Experienced editors who oversee the review process are often aware of these factors: their eyes are trained to detect biases, and they will take them into account in their recommendations.

Sin Number 9 relates to motherhood-and-apple-pie advice and insights. The self-fulfilling kind that is repeated over, and over, and over again elsewhere and in the mainstream IT media. Editors and reviewers tend to have a visceral reaction to this style of writing, and for good reason: an article peppered with clichés sounds vacous to the naked eye despite the gems hidden underneath.

Sin Number 8, when taken for granted will not only secure a stamp of rejection for your article, but may also get you into trouble. Giving credit to to others who have influenced your work will make you look better, not worse. Most submissions describe incremental improvements over previous ideas, and it’s important to acknowledge all contributions. Sometimes it feels benign to ignore to mention the source of a peripheral idea, because you’re the one who have pursued the breakthrough bit: resist that temptation. Respectable publications impose sanctions on authors who borrow without bothering to mention the lender, or fail to disclose background sources in derivative work .

Unlike research journals, professional magazines like IEEE Software have their content professionally copy edited and laid out. While this extra service allows the authors to focus their efforts on the message delivered, it still does not absolve them from paying attention to the language and adhering to common rules of good technical writing. Which brings us to sin Number 7. A poorly written article distracts the reviewers. Sometimes a substandard language kills the message, and the paper with it. Several submissions are rejected if the ideas are not communicated clearly, and reviewers can’t get passed the numerous editorial mistakes to glean the important messages from the text.

Sin Number 6 stems from a combination of overconfidence, blindness, and ignorance. Every new idea comes with caveats and compromises. Be sure to identify and declare the shortcomings of your work: where it’s applicable, where the boundaries drawn, and when it’s unlikely to work. Or suffer the wrath of reviewers who will only be glad to point them out to you and the editors. Self-awareness is your best defence against a rejection case built on the limitations of your work.

To be continued… 

Releated resources:

• Tips for Software Authors
• How to Write a Good Technical Article

 

Los Alamitos, CA

IEEE-Software-USC-UCI Joint Workshop on Software Architecture

This is a workshop sponsored by IEEE Software, USC-CSSE, and University of California, Irvine

The tentative theme is Software Architecture Challenges in the 21st Century, with the tagline…

A workshop for industry leaders, researchers, and educators who are addressing the challenges of making software development better match the ambitious requirements and fast pace of today’s projects…

It will feature some IEEE Software big guns, including…

• Grady Booch (via Second Life)
• Philippe Kruchten
• Pekka Abrahamsson
• Gregor Hohpe

Plus a day full of other talks and interesting panel discussions addressing “both real-world challenges and emerging research solutions.”

Lead organizers are IEEE Software Associate Editor Forrest Shull and  CSSE’s director Neno Medvidovic.

For the program and registration, visit http://csse.usc.edu/csse/event/2009/Arch-Workshop/pages/home.html