« Science Failure and Cubicle Brain Death | Main | Information scraps »

December 09, 2008


Thank you for this post. I am currently in the middle of writing a book and drawing a map seems like something I need to do based on where I am currently at. This will be my next activity so I can figure out if what I am writing is keeping the reader interested or not.

Spot-on, Andy!

Now that you have shown us how to become a pragmatic progammer, thinker, and learner, why not write a book "Pragmatic Writing" to teach us novice technical writers how to become an entertaining writer like you. I'm sure there's quite a bit to tell about the analogies between pragmatic code and pragmatic text.

I've repeatedly found that my best technical papers are a result of making a story-boarded presentation of the material before writing the paper. The act of creating a engaging presentation tends to force a mapped narrative.

Interesting Article. I have never thought of the map metaphor before, but usually when I get an idea, I will visualize it in my head and work on it with an "inner narrative" (i.e. talking to myself) before writing anything down. Sometimes I can spend weeks thinking about something before I write anything, and when I finally do, the writing itself is often just a mechanical process of transferring what's already in my head onto paper (or a text file).

Of course, I will spend time revising and rewriting things afterwards, but once I have made up my mind about what I am trying to say, rewriting it is all about changing the words and sentences to make the meaning clearer to the reader. I find the writing most difficult when I have not clearly defined what I want to communicate. Even if I am able to construct beautiful sentences with excellent wording, the resulting text will be complicated and hard to understand if the idea is not fully developed in my head first.

One problem with my inner narrative and visualization process is that I have to keep everything in my head for an extended period of time. Sometimes this can lead to things being forgotten and ideas "falling out" before I have been able to write them down. Maybe literally (or mentally) drawing an overview map and plotting paths on it will help ease the transition process from thoughts and visions to words. At least, I think it's worth a try. Thanks for the tip!

Anders: It helps to write everything down from the start, even if you know that what you are writing doesn't make much sense yet. You'll find it much easier and faster to mold a text like that into something that you do like, instead of endlessly tossing it around in your head first. You will also forget much less, and you will stay more motivated by seeing something on paper.

As Andy says, writing is all about throwing away text you wrote, and rewriting it into a shorter, better, clearer piece of text. It's not about getting it right the first time.

@Remko I agree. In theory I know it's better to write things down early, but I often find it hard to do so in practice. I do take notes of my various ideas and thoughts, but they are usually incoherent and hard to understand when I read them later. But I guess you are right, I should maybe just force myself to write stuff down, even if it doesn't make much sense. After all, it's better to have something cryptic on paper than not having anything when you eventually forget the original thought. Also, I guess writing stuff down frees up more space in my brain for new thoughts.

"[...] As Andy says, writing is all about throwing away text you wrote, and rewriting it into a shorter, better, clearer piece of text. It's not about getting it right the first time."

Yeah, he makes it sound so easy...

WOW, what amazing insight. You understand the creative mind (likely because you own one!), and that this makes "outlines" and strict organization tips overwhelming to us. Yet with a message to write in our hearts, your suggestion of a map of destinations and drawings is incredible, inspirational. (what fun! you mean I start my writing project with an art project??! I love it! Where were you years ago??) I am so grateful to have found you and will check back often for further thoughts...(please write them!) God has truly given you a gift in this understanding of writing, and I am stepping away from my computer with new zeal and vision of how to accomplish my goals in this arena... and after a bout of discouragement feeling a smile in my heart, and at last like I truly can "get there from here!" Invigorating. Thank you, thank you.

Verify your Comment

Previewing your Comment

This is only a preview. Your comment has not yet been posted.

Your comment could not be posted. Error type:
Your comment has been posted. Post another comment

The letters and numbers you entered did not match the image. Please try again.

As a final step before posting your comment, enter the letters and numbers you see in the image below. This prevents automated programs from posting comments.

Having trouble reading this image? View an alternate.


Post a comment

Your Information

(Name is required. Email address will not be displayed with the comment.)

About Me

  • Andy Hunt is co-founder of The Pragmatic Programmers, LLC, and is well known as a programmer, author, and publisher. His email signature, "/\ndy", dates back to the paleolithic days of uucp and ihnp4.

    See my home page. Follow me on twitter at @PragmaticAndy or subscribe to this RSS Feed

Books I've authored

Where I'm Speaking

Are you a nerd?

  • I am nerdier than 96% of
all people. Are you nerdier? Click here to find out!
AddThis Social Bookmark Button