As the common context, I used that of a mid-sized organization in the health informatics sector with new ventures in its project pipeline and with several new ideas for improving its software processes. The examples were mostly drawn from this context and organized as HBR style cases. The cases addressed project staging, incremental development, pair programming, code inspections, role of evidence, and test-driven development.

The event was a repeat of an earlier course I gave in June for for Siemens in Erlangen, Germany. But I changed the materials and format significantly to fit the new  interaction style and  in response to the feedback I have received after the Erlangen version. I divided the material into 5 modules, incorporated smaller examples, and added take-home exercises for each module. I also frequently used LiveMeeting’s poll feature to engage the audience. All in all, I think the format worked very well, surprisingly with very few technology glitches. The tech support supplied by host was very good.

The course description is available here. If you were a participant and haven’t filled out the course evaluation form, you can find it here. I have opened this post for comments: if you have any, well, what are you waiting for? Do fire.

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 omniprescence
• 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. And I felt 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. And 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 would they provide. He wanted me to document the underlying decisions. In a nutshell, he demaned that I did 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. Interstingly, 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. And that grit did not interfere with planning and running the project as a highly incremental and iterative one. Actually it turned out be a lubricant rather than a contaminant. I grew up, I suppose.

 The letter writer states that he has been researching the reasons of “our” (or “my”?) economic crisis and states that he’s found a strong indicator of what kind of management behavior the future wants. Apparently it’s not exactly what my editorial describes (never mind my editorial was not about management behavior at all). The letter writer attaches the same connotation to the term “superprofessionalism” — which I coined to describe a set of behavioral traits that represent a sort of high-order professional conduct — as the false, shallow stardom associated with the kind of people featured in reality TV series like Supermodel, The Apprentice, or  The Bachelor.  (For a synopsis, the traits mentioned in the editorial are: focus on individual responsibility, acute awareness, brutal honesty, heightened sense of fairness, resilience under pressure, attention to detail in perspective, and pragmatism first). He alleges, those kinds of media programs and my article represent the last dying attempts to revive an old-economy thinking in which all-knowing individuals hold and dispense all power. He adds that my article advocates individual and central decision making at the expense of group decision making, and is counter to holistic team behavior and denies the emergence of information and collective intelligence from decentralized interactions in social networks. But the best stretch is when he puts the blame for the current economic crisis on the kind of thinking my writing encourages, like, say brutal honesty (he in particular picks on this trait, stating that it’s socially unacceptable).

Oh? Interesting perspective, although it beats me completely how any of that can be inferred from my editorial. If it could, that perspective would represent a truly curious internal paradox on my part, given my links to the the agile software development community and in light of my previous column on the role of diversity in software development.  But one can never underestimate the intellectual depth of those who can with great facility read the sub-sub-subtext between the lines. Honestly, can anyone detect any nuances in that writing,  implanted with the idea to recreate or preserve old-world power? And me at the center of the conspiracy?

Cheers

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 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

 

To subscribe to my posts, click on the icon at  the top right corner.