Workshop: Writing About Programming

Although this workshop is oriented towards those who wish to publish articles and books, it will also be helpful for anyone who needs to write about computer programming.

I've taken numerous writing workshops, and the very best ones have had a simple model: we write, then we review what each person has written. This workshop will follow that same model, with the exception that we will be writing about computer programming.

Any programming language is acceptable, as long as you know it well enough to write about it. In fact, different programming languages are encouraged, because if others in the workshop don't understand the language, it means you must be especially clear in your writing. If you want, you can use C, Python, Perl, Ruby, or even JavaScript. SmallTalk, Lisp, Objective-C and Eiffel are all fine, and would add to the interest of the course. Chuck and I don't need to know the language you're explaining -- in fact, you're forced to write better if we don't, since we can't make any leaps of understanding about languages we don't know. Also, the level of complexity of the examples you create is not important -- they can be simple or complex. The course is about clarity in thinking and expression, not the particular programming technology.

The workshop consists of a sequence of exercises where you'll be given a program to write in your language, and then you will write about that program in order to either clarify the process of writing the program, or to make a point about the program or the language.

After each writing exercise has been completed, we will review each person's results, either as a class or in groups. We will discuss the structure of the code, whether the code could be rewritten in a fashion that would make the intent of the article clearer, whether the code could be refactored to improve it, or whether additional examples might produce more understanding on the part of the reader. We will also review the prose that describes the code, and evaluate ways it might be made clearer, more succinct, or expanded to more completely describe a concept.

The goal of the reviews will not be to criticize, but to teach you how to improve your own presentation style within a supportive environment. Attendees will learn as much from the evaluation of other's work as they do from their own.

We will also look at the issue of writing a computer programming book: choosing the topic, structuring the book and the chapters, and approaching the writing process.

We will also cover the business aspects of books and articles:

• How to get an article published
• How to get a book published
• The book publishing process

Weather permitting, we will also have hikes and barbeques. This should not only be an excellent learning experience, but a lot of fun as well.

Preparation: come with your notebook computer loaded with the programming language development tools and writing tools of your choice.