Thursday, August 17, 2006

Weinberg on Writing, Knuth, Java to Ruby, DITA Intro

This article appears in slightly different form in the July/August 2006 issue of IEEE Micro © 2006 IEEE.

This article looks at old masters and new challengers.

Words from the Masters

In this section I look at works by two of the most respected and most prolific writers in the field of computer programming and beyond.

Weinberg on Writing -- The Fieldstone Method by Gerald M. Weinberg (Dorset House, New York NY, 2006, 208pp, ISBN 0-932633-65-X,, $24.95)

Gerald Weinberg has 40 published books to his credit, so I was eager to read about the techniques that work for him and have worked for many participants of his writing workshops. He describes his approach to writing as the fieldstone method. It derives from the first lesson he learned in college: only write about things you care about. As a result, he goes through life noticing what he cares about and making notes. These unordered notes are like the fieldstones you might collect to make a stone wall. He goes to great lengths to ensure that he can find these notes when he needs them. Then, when he decides that he wants to write about something, he gathers appropriate fieldstones and builds a book or essay the way a skilled stonemason would build a wall.

Building a wall requires you to select the right stones, organize them, and then assemble the wall -- trimming and polishing to make the best wall you can with what you have. Writing by the fieldstone method requires the analogous actions. Weinberg has developed principles and procedures for all of those actions. He describes them in this book, using frequent anecdotes and many exercises. These slow you down and keep you from skimming -- like the chunks of celery that make you chew your potato salad thoroughly.

Weinberg shows how his methods prevent writer's block, the paralyzing affliction that can lead writers into addictive behaviors that keep them from working for weeks at a time. He regards writer's block not as a disorder in you, the writer, but as a defect in your methods. It is natural to have too few or too many ideas. The problem comes from what you do about it. Weinberg tells you to ask yourself the Goldilocks question: is the number of ideas I have to work with too many, too few, or just right? Depending on the answer, you gather more ideas, dump some, or start trimming and polishing the ones you have.

Weinberg mixes his practical techniques with what we referred to as "new age" in the 1970s. One of his students writes that Weinberg offers intangibles like "motivating, raising self-esteem, building confidence in writing, considering self-other context, teaching the true meaning of discipline, thinking more clearly, and raising awareness." I'm sure this comes across more powerfully in his workshops, but it is amazing how much those intangibles come through in this short book.

Weinberg addresses the mechanics of selecting, organizing, trimming and polishing. Here he gives excellent advice, including some practical techniques for achieving the famous dictum of Strunk and White: omit needless words.

Weinberg addresses the difficult problem of knowing when to stop. The fieldstone method makes this easier than other approaches do. For example, if you start by developing an outline, you may be held up by even a minor point that you may not be able to provide right away. He likens it to waiting for the number that completes your card in a game of bingo. I thought of that analogy as I read Donald Knuth's latest contribution to his magnum opus, The Art of Computer Programming. 

Other authors are stopped by their desire for perfection or their fear of criticism. All of these seem silly in the context of building a fieldstone wall.

Weinberg provides useful anecdotes about his own experiences with publishers. The Psychology of Computer Programming was not his first book, but it was his first blockbuster. Aspiring writers may find it encouraging that Weinberg had difficulty finding a publisher who would take it. He persisted, and finally found a publisher. When I reread parts of that book recently, I remembered how radical they seemed in 1971. As I look around at today's programmers, I see that their underlying ethic and approach contain much that came from that book  -- even though few programmers have ever heard of it.

This summary is no substitute for reading the book. I have left out many good parts that are hard to summarize. For example, I'd like to steal the entire chapter on plagiarism. If you want or need to write, this book can help. It is full of practical advice that can help you succeed.

The Art of Computer Programming, Vol. 4, Fascicle 4 by Donald Knuth (Addison-Wesley, Reading MA, 2006, 128pp, ISBN 0-321-33570-8,, $19.99)

Don Knuth received the ACM Turing award in 1974, became a Fellow of the British Computer society in 1980, was a charter recipient of the IEEE Computer Pioneer award in 1982, and received the J.D. Warnier prize for software methodology in 1989. He holds the unique title of emeritus professor of the art of computer programming at Stanford University.

When I reviewed the second edition of volume 3 of The Art of Computer Programming (Micro Review, Sept/Oct 1997), I compared the entire work to Herman Melville's Moby Dick. I did not mean that it constitutes an obsession on Knuth's part. Rather, it is, as Moby Dick is to students of literature, a work that you should study when you begin your career and reread as the years go by. Unfortunately, this is only partially possible. Though Knuth announced six volumes in 1969, he has to date completed only three, and there is no firm schedule for the rest. In fact, his greatest accomplishment, his single-handed design, programming, and documentation of the TeX system for document preparation, intervened. He spent many years developing that tool and then spent more years using TeX to "reimplement" the first three volumes.

Knuth has now devised a scheme for publishing the remainder of The Art of Computer Programming a little more quickly. Inspired by Charles Dickens, a nineteenth century English author who published novels in serial form, Knuth has begun to publish volume 4 in parts, or fascicles. In the last year he has brought out 4 such installments. The first fascicle, long-time Knuth fans will be delighted to hear, describes MMIX, an imaginary computer to replace the thirty-five year old MIX, the imaginary computer he used to describe algorithms in his original work. While MIX represented an idealized mixture of the assembly languages of 1960s era computers, MMIX is "A RISC Computer for the New Millennium."

Volume 4, as originally announced in 1969, covers combinatorial algorithms. Fascicles 2 and 3 deal with generating tuples, permutations, combinations, and partitions. These lead up to fascicle 4, which deals with generating trees. This fascicle also reviews the history of generating combinatorial patterns. For example, King Wen devised the I Ching in 1143 BC, and it is still a bestseller today. It has 64 chapters, corresponding to 64 hexagrams in which each of the six lines has one of two values -- yin or yang.

I can't in good conscience urge you to rush out and buy this book (unless you're a librarian). Aside from designers of searching algorithms, most people will not find it directly relevant to their work. Nonetheless, it is important as part of a coherent encyclopedia of computer science. And there is the added incentive that Knuth will pay you $2.56 for each typo that you find.  

Like the monks moving the Tower of Hanoi, Knuth soldiers on. I hope he lives long and prospers, and I hope he never finishes.


Our industry has many stories of challenges to accepted ways of doing things. Some of the challenged leaders lost their positions. Others held on. Here are books about new technologies that challenge accepted leaders.

From Java to Ruby -- Things Every Manager Should Know by Bruce Tate (Pragmatic Bookshelf, Raleigh NC, 2006, 164pp, ISBN 0-9766940-9-3,, $29.95)

Bruce Tate is a consultant specializing in persistence and lightweight development in Java and Ruby. He is the author of the award winning Better, Faster, Lighter Java and a number of other books. He wrote this book for managers, or for developers who are advising managers, who are considering moving some development projects from Java to Ruby.

Java has come a long way since its introduction eleven years ago. In the May/June 1996 Micro Review, I described the design processes by which C++ and Java put themselves forth as object-oriented successors to C. I also wrote at the time:
I think Java will eventually replace C, but I think C++ will persist as its competitor for a long time. That conflict will probably follow the model of the RISC vs CISC wars, so that ten years from now it will be hard to know which is which.
Those ten years have gone by, and Java has acquired a lot of the complexity of C++, especially in the competing frameworks that developers must evaluate and learn to use. Meanwhile, a number of more nimble languages have acquired large communities of users. According to Tate, one of those languages, Ruby, in the form of the Ruby on Rails framework, presents a better solution than Java for an important class of problems: database-backed web applications.

Tate makes the point that moving to a new computer language is risky in many ways. You should not consider it unless you see serious problems with your current situation. Tate suggests that you consider Java's greater complexity and lower productivity as risks to be balanced against the risks of moving to Ruby. He sees a large part of Java's complexity as coming from the various frameworks that Java programmers must use. He compares this with the simplicity and productivity of Rails.

Tate presents other arguments and provides greater detail. He doesn't try to decide for you, but if you decide to try Ruby, Tate provides detailed strategies for migrating and for coexisting with Java. Tate acknowledges that not everybody agrees with his point of view. He has a pro-Ruby bias, but he presents the arguments on both sides. He includes the comments of many industry experts, most notably Martin Fowler, who are frustrated with Java's deficiencies. 

If you are seriously considering a change of this sort, you should read Tate's book carefully. 

Introduction to DITA -- A User Guide to the Darwin Information Typing Architecture by Jennifer Linton and Kylene Bruski (Comtech, Denver CO, 2006, 348pp, ISBN 0-9778634-0-9,, $50.00)

Most software products require some sort of documentation, above and beyond what the bare user interface provides. Providing that documentation has traditionally been the task of technical writers. Those writers produced manuals: printed or online books that covered the subject sequentially. 

Over the last ten to fifteen years, many movements have converged upon a model of documentation that throws away the book. In this model, writers write topics -- atomic pieces of information that they recombine as needed and present to users online on demand. Users press a help button specific to the task they are working on or use indexes, tables of contents, or search engines to find the topics they need. Topics typically describe procedures, but they can also explain concepts or provide reference information.

As this model has developed, writers have tried to achieve its goals by using the available book-oriented tools. In the area of structured writing, this meant using the Docbook system, which was originally developed in the 1980s to work with SGML (Standard General Markup Language, an ancestor of XML). The Docbook DTD (document type definition) is in widespread use with XML publishing tools today.

Darwin Information Typing Architecture (DITA) marks a clean break with the book model. Its designers at IBM started from topics. They introduced a system of maps to take the place of the structure imposed by a book. Maps externalize dependencies and cross references, which facilitates automated recombination and reuse of topics.

Until now, there have been few organized presentations about DITA for writers. Linton and Bruski try to fill that need. They build the book around a complete online help system developed in DITA from the ground up. If you work your way through it, you will learn how all the pieces fit together. 

Unfortunately, the book does show signs of the speed with which it has been brought to market. Its structure is a combination of parts, sections, and lessons, but no chapters. It appears to superimpose a book's outer trappings onto a set of lecture notes and lab instructions. Also, the editing leaves a lot to be desired.

If you are in a hurry to understand DITA, this book can help. If not, you might want to wait for the second edition.