How to Write Without Writing

I have a confession to make: in a way, I founded Stack Overflow to trick my fellow programmers.


This is a companion discussion topic for the original blog entry at: http://www.codinghorror.com/blog/2011/02/how-to-write-without-writing.html

While I agree communication skills are important, I’m not sure you should be quoting Joel Spolsky. While he sounds a great bloke to work for, I’ve never seen much evidence he has any great ability to write software.

This says it all for me:

“By writing clear comments and technical specs, they let other programmers understand their code”

It’s far more important to write clear code, than to write code that needs to be explained by comments and external documents.

But perhaps that what Joel meant, and he just didn’t communicate it clearly :slight_smile:

I use SEN to practice my writing skills. Practicing writing also improve your working memory. Working memory (http://en.wikipedia.org/wiki/Working_memory) is essential for the programming task. Here is a nice article about positive effect of writing on working memory: http://cogprints.org/3246/1/Olive_Euro_Psy.pdf

Yes you are very correct that communication, especially written communication is extremely important. The irony of you opening paragraph is awesome:

“I’ve come to believe deeply in the idea that that becoming a great programmer has very little to do with programming”

@Jim Cooper

I think the point is that writing is hard enough even with the whole English language at your disposal.

When you only have the syntax of a programming language, the clearest code in the word is still easier to understand with comments and a tech spec.

Thanks for another excellent and insightful article, you made me realise what I love so much about Quora.

Don’t get me wrong I have been recommending SO to people for years, as an example of how crowd sourced Q&A should work. The problem for me personally is that only a very small fraction of my near 15k of network connections are programmers.

While I value crowd source massively it is blown away by connect source. Most of my biggest problems are not ‘how does this work?’ but ‘why does it work?’ and ‘will it work tomorrow?’.

For those questions, some tenuous path back to the source of the intelligence, some prior knowledge or some common friends are far more important. But as you can see from my answer, you are dead right, it’s all about communication skills.

I’ve always found it strange that, for learning programming and similar subjects, it is easy to find very basic “hello world” tutorials on one hand, and very complex and specific information on the other. This post might be the explanation why.

One reason could be that the intermediate range of knowledge is the hardest to communicate - it regards the logic behind the technical aspects. You have to write sentences understandable to someone who doesn’t know much on the subject yet, and you need to know what not to take for granted. And putting something that you understand intuitively in words is not easy. But it is very important. Programmers should put in the effort to put into words the precious knowledge and ways of thinking that are in their heads. I thank anyone who is already doing it or going to do it in the future, including Jeff Atwood, clearly.

But in the end all sharing of knowledge is precious - even the smallest technical detail or personal experience. So do as Jeff suggests in this post. Please:)

I too have started a blog to document my learning process, and I’m finding that now I need to learn blogging as well as programming. Takes practice, but it’s very useful. Putting things in my own words also helps me understand them better. I find that if I actually try to explain a subject to myself, in writing, I realize how much do I really know, and which aspects do I need to know better. It helps me move beyond just following my intuition and later getting lost in it. I create maps for myself.

BTW English is not my first language, excuse me for any possible errors.

Finally I have a chance say thank you for this valuable blog. And for Stack Overflow. I keep thinking I need to start participating there actively, as well, but for now I’ve been reading it and it’s wonderful.

Olja Petrovic, http://apprenticecoder.wordpress.com

As much as I agree that communicating ideas are important, I have no issue discussing these things with other programmers.
It’s when you write the documents explaining everything to the people distributing the money that it becomes difficult, because most of the time, they don’t know shit. They’re just some dude with a cheque book and want to know why they should pay for an additional two weeks or why this does that and they want to know how it works… but no details? It can be very frustrating as a lot of these people also tend to be very tech illiterate.

I actually had to tell someone that no, the computer cannot process the data if you turn it off, even if you started it before hand and even though that data is on the server.

Agreed on the importance of communication skills, but there are few professions nowadays where this is not required, so it says nothing about programmers specifically.

I also think that you stereotype programmers a bit too much in the beginning paragraphs. You make it sound like they are all anti-social, projecting the Hollywood cliche onto them. In my own experience working in several large companies with large development teams, I do not see that. I see perfectly “normal” people, with adequate communication skills, a family at home, proper clothing, etc.

It seems everybody fixates on the bearded Debian hardcode C programmer, but reality in my experience is very very far from it.

Yes! You hit the nail on the head, if I can say so.
I’m a programmer and a blogger, and when I learn something new, I try to share my knowledge on my blog. This way, I better understand a new concept or something that is hard for me to understand.
Thank you for this great article.

Very interesting post. I agree completely. I struggle with writing. Not very good at all but I do attempt it on occasion. I guess I need to spend a little more time with it and see where it goes.

This blog post inspires me to continue blogging on IT and development in this industry in my island after 3 year of blogging on University Student Life and British computer Society.

Coding Horror FTW!

If everybody writes a lot, who’s gonna read ? :slight_smile:

“Yes, by God, we will trick you into becoming a better writer if that’s what it takes – and it always does.” – Seriously? It was not put into you to guide the entire development community whether we like it or not. I love how people always invoke God when they are justifying a lie.

Poor us, just too stupid to see the genius that is Jeff Atwood, so he redirects his entire career in order to build an intricate lie to get us to do what he knows is best for us and we just can’t see. Thank you Jeff Atwood for saving us. What would we ever have done without you.

I agree that communication is an important skill, one you could learn more about before trying to guide the world. If you have to lie to convince others to follow merits of your ideas then you are in fact failing at the communication you claim to be so important.

Nothing is more of a curse to the world than people who have become so full of their own intelligence that they believe they are just in deceiving/forcing others to conform to their “enlightenment”.

Personally, I think communication plays a big role in programming. But understanding what you are doing plays an even bigger role. It doesn’t matter how good of a communicator you are, if you don’t understand what you are talking about, you will completely fail at trying to work as a programmer. While I understand that there are many good programmers who just lack communication skills, I very rarely find one who has such bad communication skills that they can’t get their point across, If they know what they are talking about. While communication skills can help make a good programmer better, they can’t make a programmer who has no idea what they are doing any better.

It's far more important to write clear code, than to write code that needs to be explained by comments and external documents.

Writing comments before code can help you write clear code.

@Jim Cooper

While I can’t comment on Joel Spolsky’s ability as a programmer, his comment makes sense.

Code alone does not provide context. While you should strive to avoid redundant comments that repeat what the code does, you still need comments and technical specs to tell you why the code even exists and how it fits into the larger picture.

It’s also very helpful to point out to developers when you are using certain patterns, algorithms, etc and not expect them to just intuit it from a cleverly named class. At least you should give them enough to google with.

You also should never underestimate the invaluable aspect of writing as a problem solver. Consider how many times any of us have been stuck trying to resolve a sticky technical issue. The process of writing itself can liberate you from your situation. By carefully channeling the conditions of your issue in a linear and comprehensive text, your situation is translated from spatial & abstract to linear & concrete, which often can lead to a resolution.

Just think of how many times you’ve gone to explain a problem to a coworker and as you explain it, the riddle is solved.

@Russel – is your humor detector broken? Or maybe you’re just prone to taking things a little too literally? Jeff is just taking notice of the effect that SO has had in regard to improving some programmers’ writing skills.

Jeff and Joel, did not create StackOverflow and friends to force anyone to improve their writing skills. They did it to make money. (If not, then why are there ads on those sites?) If Jeff notices that the sites have had unexpected beneficial side effects, and writes a slightly tongue in cheek post, with specific examples, that recognizes that effect, big deal. Don’t jump the shark and assume they hatched this evil plan from the beginning to trick us all into doing something we would never have done ourselves. I know, I know–Jeff wrote that that is exactly what they did. It’s called literary license. Jebus. Take a valium.

Nicely written rant, though…

Improving my writing is one of the important motivations for maintaining a blog in the first place.