Talk About Quality

Tom Harris

Archive for the ‘Writing’ Category

Writing, Unschooled

leave a comment »

prompt /präm(p)t/ verb
2. assist or encourage (a hesitating speaker) to say something.

(credit: Google search “prompt definition”)

For example, “Write a 12 word story that uses the words ‘apple’ and ‘alarm’.”

My response:

“Leap, please,” cried the young orangutan, holding onto his mother’s feral arm.

My Writing CV

Experience

Responding to Tablo Publishing writing prompts, also on Twitter
Reading @brian_bilston on Twitter
Trying my hand at 50-word stories to accompany pictures on Seempli
Writing poetry on WhatsApp, inspired by friends
Blogging at Talk About Quality
Years of e-mails, halved before sending, because people said, “Too Long!”
Studying French and Russian in college, to avoid having to write in English
Having my English writing labeled “tortured Teutonic” by my high school English teacher
Writing Haiku when we learned about Japan in second grade

Education

My engineering senior project professor who said, “You have a word processor. Just type everything you know, and rearrange it afterwards.”

Written by Tom Harris

October 11, 2016 at 11:57 am

Posted in Education, Writing

Software is Writing

with one comment

Software is not construction

Software is not construction, no matter how popular that statement may be. A program is not a building. Parts are not chosen first and then fitted into place. Design continues almost to the last minutes of coding. Further, almost nobody spends time creating new code, at least not for very long. Sure there are new products and new codebases. But even then, after a short period, most additional coding is extending or changing an existing codebase. So if coding is not construction, and mostly involves changing what’s already created, what is it?

Well, coding is writing. It’s using text to communicate a message. That may not sound like much, but understanding this helps a lot. Instead of struggling to make up new ways of thinking and learning, as if programming were a completely new human activity, we can look at how good writers write. People have been writing for many hundreds of years, and have become pretty good at it.

Learning to write

How do people get into writing? Do we start, as most do in programming, full grown, writing essays? No, not at all. We start as children, and learn first to talk, then to read, and finally to write. Yes, I know that school seems to teach writing, at least forming the letters, before reading. But it’s an illusion: listening to a bedtime story is essentially reading – paying attention to someone else’s writing, and understanding it – and comes before writing. Most people don’t try writing that communicates a message – expository prose – until secondary school or later.

Good writers have their audience in mind at all times. They edit their writing through several drafts, as well as getting others to review it, and give written comments. And they talk about their writing. Maybe not always directly, but when a political columnist goes to a dinner party, you can bet he’ll talk politics. When a novelist chats in the park, she’s talking about the same human struggles that will later appear in her books. Even for the solitary writer typing in a darkened room, the life that feeds the writing is one of talking with, listening to, and reading about people.

Software is Writing

Now back to software: software is not like writing, it is writing. In our industrial setting, it is too late or too radical to suggest re-teaching programming, by teaching first how to talk, then to read, then to write programs. But we can highlight where daily programming work already involves each of these three activities, and where it doesn’t, but should.

Talking includes formal design reviews and code reviews, but also whiteboard conversations and hallway arguments. How should I write this here? Why is that data structure that way? Why does the compiler give that warning? Don’t just think alone – talk it out with someone nearby. It is the same with tests. Why does that scenario fail intermittently? How should I write it differently? And even for defect entries -what does the submitter really mean? Phone him up. Why does this change fix the problem? Find the developer and ask.

Reading is for design documents, training materials and perhaps professional books. But mainly, it includes reading lots of existing code. That’s reading it until you’re really sure what it does, so you know how to change it, fix it, extend it. There is also code review — where the author asks you to read their code, not just to say that it looks fine, but to identify what’s wrong, or unclear.

Writing is the coding, of course. But who is the audience? There are two audiences. One, the compiler, which is your personal translator, from a non-native language (nobody’s mother spoke to them in C), to an almost unknown language – the machine language that the hardware actually understands. The compiler is a rigid, simple-minded, sometimes unpredictable audience, just a ghost of the person who wrote it. Here you have to be very precise, careful, and limit yourself to what the compiler understands and to what the hardware will accept. The other audience, is so very different – the next developer. This may be yourself a few weeks later, or someone else, but there will always be another developer, coming back months or years later, to fix or extend the code. She wants comments, explanations, meaningful names for things, and an easily readable structure. Because now you’re long gone, she can’t talk to you: she must read, so you must write.

Tools!

Well, with all this talk about programming being writing, let’s come back to earth. Software developers are technical people, and expect to use the best tools to do their jobs. There’s the whiteboard in the hallway — we need more of those, for talking. Defect tracking systems, where we can make sure we write clear resolution notes. And for automatically sharing and discussing code, web-hosted code tools for static analysis and code review are the way to go.


Originally published in company internal newsletter. Edited and released here with permission.

Written by Tom Harris

September 15, 2010 at 1:51 am

Posted in Software, Writing

The Only Valid Measure of Code Quality

with one comment

It’s Thom Holwerda — keeping things simple for us:

Simple Code Quality Metric

Simple Code Quality Metric

Here’s his site — with a search for “code quality” (warning: if you can’t ignore “Evony” web game ad graphics, stay away).

Written by Tom Harris

July 16, 2009 at 4:13 am

Posted in Code Review, Writing

Books as a Means of Communication

leave a comment »

Yesterday, for the first time in a long time, I had a chance to work with someone who had recently read the same book that I had. We happened to be talking about different categories of tools. It was a great session — we got a lot done.

What is a book itself a tool for? And how is it a means of communication?

The answer seems obvious: a book is an author’s way of communicating with a large audience. But the obvious answer is mostly wrong. While there is a one way “broadcast” in a widely-published book, that’s not the major benefit, and it’s certainly not two-way communication. Rarely do readers get to speak with book authors.

For writers, a book is often a way to get thoughts out of one’s head and out on paper so one can think again. And, if it’s a great book, a chance to enjoy creating a work of art as well.

But for readers, the book is a tool. It is an application-specific language for conversations in the book’s field or topic. If you’ve ever had trouble getting to the point in a discussion because it takes so much time to set the stage, a book is missing. Complex subjects are best addressed first in writing. If both participants read a book, they can use the concepts that the author has spent months or years defining and refining, and start their conversation on the same wavelength.

Want to jump-start productive conversations? Read a good book.

Written by Tom Harris

May 9, 2006 at 10:48 am

Posted in Technology and Society, Writing

Tagged with