Joel on Software Writing

A few interesting points ( mostly paraphrased) from a forty minute interview with Joel Spolsky on software writing:

• Most software writing is awful. There is a high correlation between successful software and writing.
  
• Programmers are used to writing code for compilers; compilers don't care about order. Humans comprehend stories - can't give them a bunch of definitions and tie it together. Most programmers, who write for compilers , don't know how to write for human brains.
  
• There is an awful lot of writing there about technology, even internal functional specifications that just doesn't get read, because regular people don't understand it.
• At Fog Creek software (Joel's company) they ask for writing samples, not necessarily technical stuff from all candidates. Because we (Fog Creek) really do find that the ability to communicate clearly and effectively, is the crucial difference between an acceptable programmer and a great programmer that can work on teams, and get their ideas understood by the world.
  
• Once you make software that mediates between humans, then the design decisions in the software have anthropological implications. In Joel's latest book, Danah Boyd talks about some websites that require a strict social relations - such requirements are pathological, not normal. People are actually creating software and websites that require you to conform to a set of behaviors that in the real world would get you incarcerated.
• Paul Graham's assertions about great hackers - they use open source, they don't use Java etc flies in the face of facts. But his essays are beautifully written. Joel said his hands start shaking whenever there is a new post on Paul Graham's site.
  
• Phil Windley asks an interesting question about whether it is opninions that make software writing interesting. Joel says that's where the value is being added (in opinions) and goes on to add that with great respect to the American journalistic tradition of objectivity, the only thing it results in is lot of cnet's news.com, that is very bland, that reproduces a lot of press releases , or they get someone from Sun to say something about Microsoft's announcement.
• According to Joel, the number one rule of technical writing is, "Show, don't tell". Technical writers violate that rule so often. So much technical writing reads like mathematical proof - all the information is here, if you can decipher it, you can understand it. That kind of stuff doesn't get read unless it has to get read. The stuff that people read are the ones with stories in it. Human beings are story tellers. We have been telling stories around camp fires for hundreds of thousands of years - that's what out brains are good at and that's we enjoy, that's why TV is popular and that's how messages get into our head.
• When people started using PC's there was lot of piracy, lot of the books were just shovelware. Companies were trying to make the books as fat as possible. At one time software could not be used without books. It was not until the GUI generation and much later, that software companies realized that they don't have to produce the manuals at all. These days some of the best books are the ones written to explain the domain in which software is used. Quick Books' manuals, for example, teach you a lot about the basics of book keeping.
• Amazon ratings are not accurate and are not done by professional people ( I personally disagree with this sweeping characterization). Joel said that there were folks with axes to grind who wrote reviews on Amazon and gave the example of a Microsoft techie, whose book got bad ratings, because he used to be aggressive in some news groups.
• If you are a computer programmer, put yourself in another person's mind - what do they know at any given time ? Try to answer the questions in their minds in the order in which they are having it. If you write a document the reader first with what the document is about, and start answering the questions that they might have in their minds.
  
• Some of the great functional specs are written like a story.
  
• Blogging is a good way to exercise the writing muscle. Joel noted that he had gotten a bit over defensive in his writing of late.