Clear Communication

This is a collection of links regarding why clear written communication (using proper spelling, grammar, syntax, punctuation, semantics, etc.) is important.

Joel Spolsky's “Advice for Computer Science College Students”

 * The Article

The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and it's not whether they prefer Python or Java. It's whether they can communicate their ideas. By persuading other people, they get leverage. By writing clear comments and technical specs, they let other programmers understand their code, which means other programmers can use and work with their code instead of rewriting it. Absent this, their code is worthless. By writing clear technical documentation for end users, they allow people to figure out what their code is supposed to do, which is the only way those users can see the value in their code. There's a lot of wonderful, useful code buried on sourceforge somewhere that nobody uses because it was created by programmers who don't write very well (or don't write at all), and so nobody knows what they've done and their brilliant code languishes.

Eric S. Raymond's “How to become a Hacker”

 * The Article

4. If you don't have functional English, learn it.

As an American and native English-speaker myself, I have previously been reluctant to suggest this, lest it be taken as a sort of cultural imperialism. But several native speakers of other languages have urged me to point out that English is the working language of the hacker culture and the Internet, and that you will need to know it to function in the hacker community.

Back around 1991 I learned that many hackers who have English as a second language use it in technical discussions even when they share a birth tongue; it was reported to me at the time that English has a richer technical vocabulary than any other language and is therefore simply a better tool for the job. For similar reasons, translations of technical books written in English are often unsatisfactory (when they get done at all).

Linus Torvalds, a Finn, comments his code in English (it apparently never occurred to him to do otherwise). His fluency in English has been an important factor in his ability to recruit a worldwide community of developers for Linux. It's an example worth following.

Being a native English-speaker does not guarantee that you have language skills good enough to function as a hacker. If your writing is semi-literate, ungrammatical, and riddled with misspellings, many hackers (including myself) will tend to ignore you. While sloppy writing does not invariably mean sloppy thinking, we've generally found the correlation to be strong — and we have no use for sloppy thinkers. If you can't yet write competently, learn to.

How to improve your English
1. Write. Write a lot. Start a blog. Write about interesting stories from your past. Ask your readers to point to the issues in your text (also your code). Maybe start specialised blogs for writing about a topic that interests you.

2. Read. Read a lot. Especially fine literature, though not too archaic. I really like reading original and quality Children and Young Adult's Literature in English (e.g: The Hobbit, The Treasure Island, E. Nesbit, Roald Dahl, Mary Poppins, Sherlock Holmes, etc. - can't think of more right now.) There are many public domain and freely distributable fiction online in Project Gutenberg,

3. Pay attention to what you write and how you phrase yourself. Don't write too hastily.

4. Chat with English speakers on IRC - I like Freenode for that and they have an ##English channel. Other channels accept somewhat off-topic discussion, especially some #not-* channels or *-social channels, which are intended solely for offtopic discussion.

5. Watch/listen to some films to see how people use the English language in speech. There are many clips on YouTube and similar sites and you can learn a lot from them. There are some larger scale videos available online, offline, and on torrents naturally.

6. Most importantly - remember that improving your language is hard work, but it's also fun, because hard work is often fun and rewarding and makes you happy. The opposite of fun and pleasure is not necessarily work. If people did not enjoy hard work for pleasure, then large scale operating systems that are completely free-and-open-source-software such as GNU/Linux or the BSDs could not happen.