Docstoc

how_to_write_a_good_technical_article

Document Sample
how_to_write_a_good_technical_article Powered By Docstoc
					                                from the editor
     Editor in Chief: Steve McConnell                        I   Construx Software     I   software@construx.com




How to Write a Good
Technical Article
Steve McConnell




                                I
                                    EEE Software receives about 200 man-            As a magazine, IEEE Software has more
                                    uscripts each year, of which we publish      latitude than a transaction about the kinds of
                                    approximately 50 to 75. Each manu-           articles it publishes. We can publish reports
                                    script goes through an in-depth peer         of a single project or company’s experiences,
                                    review process and is reviewed by our        and the findings need not rise to the level of
                                    associate editors in chief and me. In        statistically significant research if they pro-
                                addition, guest editors review special-issue     vide valuable insights to our readers. Arti-
                                manuscripts.                                     cles can also describe experiences with a new
                                  Four years as editor in chief of IEEE Soft-    tool or practice, new ways of using old prac-
                                           ware have shown me countless ex-      tices, new combinations of old practices,
                                           amples of the differences between     and so on. However, experience backed by
                                           good and not-so-good technical        data has a better chance of being published
                                           articles. You might have wondered     than purely anecdotal experience reports. Of
                                           what you need to get a technical      course, we are also always looking for re-
                                           article published, either in IEEE     search findings that do rise to the statistically
                                           Software or elsewhere. Here are       significant level, as long as those findings are
                                           some pointers.                        of interest to leading software practitioners.
                                                                                    An important factor in my decision about
                                            Content                              whether to accept an article is how clearly the
                                               One frequent misperception        article is focused. A good article addresses ex-
                                            about IEEE Software is that it is    actly one topic. I have been surprised at how
                                a “journal.” In common parlance, IEEE            many submissions cover one-and-three-quar-
                                Software probably is a journal in the sense      ters topics poorly rather than cover one topic
                                that it publishes substantive papers of inter-   well. The solution is often simply to remove
                                est to leading practitioners. In IEEE par-       extraneous material. As Voltaire pointed out,
                                lance, however, IEEE Software is a magazine      an article is finished not when there is noth-
                                rather than a transaction or journal. The dif-   ing more to add, but when there is nothing
                                ference between these terms in IEEE-speak is     more that can be taken away. Similarly, a
                                that a magazine publishes articles and           good article has a clear purpose. If I can’t de-
                                columns of contemporary interest to practi-      termine the point the author is trying to
                                tioners. Transactions focus more on publish-     make, I won’t accept the paper.
                                ing research results. There is no strong ex-        Our referees and readers have told us they
                                pectation that a transaction’s readers will      dislike articles that evangelize a specific tool
                                read its papers as soon as they are published;   or methodology, especially if one specific
                                rather, we expect readers to archive a trans-    company sells that tool or methodology.
                                action for future research purposes. We ex-      Candid experience reports are always wel-
                                pect magazine readers to read a magazine’s       come; dressed-up marketing pieces rarely
                                contents close to when we publish them.          make it past my desk into the review process.

Copyright © 2002 Steven C. McConnell. All Rights Reserved.                             September/October 2002   IEEE SOFTWARE   5
                                                                                                   FROM THE EDITOR


                                                                     In contrast, our readers like articles      Lack of focus in multiauthor papers
                                                                     about real, hands-on experiences. I            Many papers we publish have mul-
                   D E PA R T M E N T E D I T O R S                  give leeway to articles based on            tiple coauthors. These papers frequent-
                  Bookshelf: Warren Keuffel,                         hands-on experiences, submitted by          ly suffer from redundant sections writ-
                   wkeuffel@computer.org                             working practitioners who might not         ten by different authors, from writing
        Construction: Andy Hunt and Dave Thomas,                     be well-versed in the nuances of writ-      styles that differ grossly from one sec-
                 Pragmatic Programmers,
         {Andy, Dave}@pragmaticprogrammer.com                        ing for publication. As long as you         tion to the next, and so on. Coauthor
           Design: Martin Fowler, ThoughtWorks,                      clearly and honestly report the expe-       teams should appoint a lead author or
                     fowler@acm.org
                                                                     rience, you don’t need to worry about       editor who can make a final pass
Loyal Opposition: Robert Glass, Computing Trends,
               rglass@indiana.edu                                    the writing being perfect. IEEE Soft-       through the paper to check for redun-
         Manager: Don Reifer, Reifer Consultants,                    ware’s excellent staff of editors can       dancy and inconsistencies.
                dreifer@sprintmail.com                               turn the report into a publication-
             Quality Time: Jeffrey Voas, Cigital,                    quality article as long as the writing is   Overgeneralizing from experience
                      voas@cigital.com
                                                                     technically accurate.                          While our readers love experience
                              STAFF                                                                              reports, I find that authors sometimes
                       Senior Lead Editor                            Writing style                               draw conclusions that extend beyond
                          Dale C. Strok
                      dstrok@computer.org
                                                                        The best style for a technical arti-     their reported experiences. For exam-
                                                                     cle is to present background informa-       ple, a paper that reports how much
                     Group Managing Editor
                        Crystal Chweh                                tion and technical conclusions as           developer morale improved after us-
                    Associate Editors                                clearly as possible. Other objectives       ing certain technical practices should
     Jenny Ferrero, Shani Murray, and Dennis Taylor                  are secondary to clarity.                   not speculate that productivity will
                       Staff Editors                                    I have received papers in which          “probably” or “obviously” improve.
         Scott L. Andresen and Kathy Clark-Fisher
                                                                     the author seems to be trying to im-        Similarly, a paper can’t claim that a
                     Editorial Assistants
                Rebecca Deuel and Ty Manuel                          press readers with his or her intellect.    method improves portability, main-
                   Magazine Assistants                               Some papers use large words when            tainability, or adaptability until the
            Dawn Craig, software@computer.org                        synonymous shorter words would              software concerned is ported, main-
                         Pauline Hosillos
                                                                     suffice, and others use sentences that      tained, or adapted. A paper provides
                           Art Director
                         Toni Van Buskirk                            are longer and more complicated             significant value by reporting even
                         Cover Illustration                          than needed. Some papers create a           simple, narrow findings, but specula-
                           Dirk Hagner                               profusion of needless acronyms or           tion beyond what the experience or
                       Technical Illustrator                         use mathematical formulas to present        data supports detracts from a paper’s
                           Alex Torres
                                                                     concepts that could be presented            contributions.
                       Production Assistant
                        Monette Velasco                              with one or two short sentences.
                    Production Artists                                  IEEE Software’s audience is soft-        Too much academic background
           Carmen Flores-Garvey and Larry Bauer                      ware practitioners. Leading practition-     information
                        Executive Director
                         David Hennage
                                                                     ers are busy people who place a pre-            Many papers spend pages provid-
                            Publisher
                                                                     mium on accessible information. Big         ing background information on a fa-
                         Angela Burgess                              words, complicated sentences, and for-      miliar topic—for example, the Soft-
                       Assistant Publisher                           mulas don’t impress them. Our readers       ware Engineering Institute’s CMM for
                           Dick Price
                                                                     value articles that quickly and bla-        software. A college term paper might
         Membership/Circulation Marketing Manager
                    Georgann Carter                                  tantly cut to the heart of the issue at     require such background, but a paper
                      Advertising Assistant                          hand. The more practical the article,       submitted for consumption by practi-
                         Debbie Sims                                 and the more it is directed toward          tioners does better to provide a one-
                  CONTRIBUTING EDITORS                               practicing software developers and          paragraph summary of familiar topic
                 Candace English, Greg Goth,                         managers, the more likely we are to         areas and direct readers to seminal
                Keri Schreiner, and Joan Taylor                      publish it.                                 books or articles on the topic. Readers
                                                                        The highest praise an IEEE Soft-         are more interested in the author’s spe-
    Editorial: All submissions are subject to editing for clarity,
                                                                     ware article can receive is “It seems       cific experiences than in reviewing fa-
    style, and space. Unless otherwise stated, bylined articles      like common sense.” If an author can        miliar background material.
    and departments, as well as product and service descrip-
    tions, reflect the author’s or firm’s opinion. Inclusion in      present a new concept so clearly that
    IEEE Software does not necessarily constitute endorsement        readers view it as common sense, the        Reluctance to submit a short paper
    by the IEEE or the IEEE Computer Society.
                                                                     author has accomplished something              When reviewing submitted manu-
    To Submit: Send 2 electronic versions (1 word-processed          significant.                                scripts, I sometimes get the impres-
    and 1 postscript or PDF) of articles to Magazine Assistant,
    IEEE Software, 10662 Los Vaqueros Circle, PO Box 3014,                                                       sion that the authors had a good,
    Los Alamitos, CA 90720-1314; software@computer.org. Ar-
    ticles must be original and not exceed 5,400 words including     Pitfalls                                    clear idea but felt it was too small by
    figures and tables, which count for 200 words each.
                                                                       Papers sometimes fall short in            itself to submit for publication. The
                                                                     ways that can be easily avoided.            authors then submit a paper with de-

6          IEEE SOFTWARE          September/October 2002
                                FROM THE EDITOR                                                               EDITOR IN CHIEF:
                                                                                                               Steve McConnell
                                                                                                          10662 Los Vaqueros Circle
                                                                                                         Los Alamitos, CA 90720-1314
tailed background information, col-           always improve the quality of your pa-                       software@construx.com

lateral material, and so on—which             per. If nothing else, you’ll learn what                   EDITOR IN CHIEF EMERITUS:
                                                                                                       Alan M. Davis, Univ. of Colorado
has the cumulative effect of obscuring        someone else thinks is needed to con-                          at Colorado Springs
the article’s real contribution. Our          nect with our magazine’s readers.
readers have been exceedingly clear                                                                   A S S O C I AT E E D I T O R S I N C H I E F

that shorter is better. A paper should        Details                                        Design: Maarten Boasson, Quaerendo Invenietis
make its point and then stop.                    Authors should also address a few                     boasson@quaerendo.com
                                                                                                Construction: Terry Bollinger, Mitre Corp.
                                              details that ease the reviewers’ and ed-                       terry@mitre.org
Submitting a paper that is                    itors’ jobs. Submissions should contain         Requirements: Christof Ebert, Alcatel Telecom
                                                                                                       christof.ebert@alcatel.com
inappropriate for a theme                                                                   Management: Ann Miller, University of Missouri, Rolla
   Occasionally we receive a submis-          I   Page numbers on each page                               millera@ece.umr.edu
                                                                                                      Quality: Jeffrey Voas, Cigital
sion for a theme issue that is outside the    I   An abstract or executive summary                         jvoas@cigital.com
theme’s scope. In the worst cases, the            of 150 or fewer words                           Experience Reports: Wolfgang Strigel,
author has changed the paper’s title to       I   A list of keywords                           Software Productivity Center; strigel@spc.ca

match the theme, but the contents don’t       I   Contact information for each au-                             EDITORIAL BOARD
match the title or relate to the theme.           thor on the first page
                                                                                              Don Bagert, Rose-Hulman Institute of Technology
Submitting such papers is a waste of                                                             Richard Fairley, Oregon Graduate Institute
time for everyone involved. If you            In addition, IEEE Software does not                      Martin Fowler, ThoughtWorks
                                                                                                      Robert Glass, Computing Trends
doubt whether your paper is appropri-         generally publish articles that have                  Andy Hunt, Pragmatic Programmers
ate for a theme, email the theme’s guest      been published elsewhere or that are                Warren Keuffel, independent consultant
editors. They will help you focus your        simultaneously being considered for                 Brian Lawrence, Coyote Valley Software
                                                                                                       Karen Mackey, Cisco Systems
ideas in ways consistent with their           publication elsewhere.                           Deependra Moitra, Lucent Technologies, India
theme, which maximizes the chances                                                                     Don Reifer, Reifer Consultants
                                                                                                Suzanne Robertson, Atlantic Systems Guild
that we’ll ultimately accept your paper.                                                          Dave Thomas, Pragmatic Programmers



                                              M
                                                    y bottom-line question for an
Expect to be edited                                 IEEE Software article is, “Does it                 INDUSTRY ADVISORY BOARD

    It’s natural to become attached to              make a contribution to the soft-              Robert Cochran, Catalyst Software (chair)
writing into which you’ve poured pre-         ware engineering literature?” Some ar-                Annie Kuntzmann-Combelles, Q-Labs
cious evening and weekend hours. No           ticles contribute by introducing a revo-                     Enrique Draier, PSINet
                                                                                                      Eric Horvitz, Microsoft Research
one will be more familiar with a pa-          lutionary concept or by synthesizing                      David Hsiao, Cisco Systems
per’s content than the author. How-           familiar concepts in a new way. Others               Takaya Ishida, Mitsubishi Electric Corp.
                                                                                                          Dehua Ju, ASTI Shanghai
ever, IEEE Software’s readers are ac-         contribute by providing an exception-         Donna Kasperson, Science Applications International
customed to reading articles that are         ally accessible introduction to a specific               Pavle Knaflic, Hermes SoftLab
presented in a particular style. The job      topic or by providing an unusually                Wojtek Kozaczynski, Rational Software Corp.
                                                                                                  Tomoo Matsubara, Matsubara Consulting
of IEEE Software’s professional edit-         clear and balanced survey of a topic                  Masao Matsumoto, Univ. of Tsukuba
ing staff is to ensure that each article is   area. A good article says something           Dorothy McKinney, Lockheed Martin Space Systems
                                                                                                Nancy Mead, Software Engineering Institute
ultimately published in a form that fa-       new or says something old in a new                     Stephen Mellor, Project Technology
cilitates that connection between the         way. If you have ideas about an article                      Susan Mickel, AgileTV
author and our readers. Most authors          you would like to publish, please do                     Dave Moore, Vulcan Northwest
                                                                                               Melissa Murphy, Sandia National Laboratories
don’t enjoy being edited, but if you          not hesitate to contact us at software@                     Kiyoh Nakamura, Fujitsu
keep an open mind, editing will almost        computer.org.                                     Grant Rule, Software Measurement Services
                                                                                              Girish Seshagiri, Advanced Information Services
                                                                                                        Chandra Shekaran, Microsoft
                                                                                                           Martyn Thomas, Praxis
                                                                                                   Rob Thomsett, The Thomsett Company
                                                                                                       John Vu, The Boeing Company


                 Coming Next Issue                                                                   Simon Wright, Integrated Chipware
                                                                                               Tsuneo Yamaura, Hitachi Software Engineering

                                                                                                  M A G A Z I N E O P E R AT I O N S C O M M I T T E E



                         The Business of                                                     George Cybenko (chair), James H. Aylor, Thomas J.
                                                                                              Bergin, Frank Ferrante, Forouzan Golshani, Rajesh
                                                                                             Gupta, Steve McConnell, Ken Sakamura, M. Satya-

                       Software Technology                                                     narayanan, Nigel Shadbolt, Munindar P. Singh,
                                                                                                      Francis Sullivan, James J. Thomas

                                                                                                            P U B L I C AT I O N S B O A R D

                    Making software engineering decisions                                         Rangachar Kasturi (chair), Jean Bacon,
                     that support your business objectives                                   Mark Christensen, George Cybenko, Thomas Keefe,
                                                                                                 Dick Kemmerer, Gabriella Sannitti di Baja,
                                                                                                    Steven L. Tanimoto, Anand Tripathi




                                                                                           September/October 2002            IEEE SOFTWARE               7

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:22
posted:7/6/2010
language:English
pages:3