Should programmers be able to write clearly?

Question

I read Richard P. Gabriel's book "Patterns of Software" (pdf) which contains an essay called "Writing Broadside" in which he contends that programmers should develop their ability to write clearly. I have found that his suggestions have definitely improved my ability to write tech. spec's and design documents.

One of his suggestions is to develop writing workshops at work. That this will help improve your ability to express yourself clearly when documenting your designs.

We already have a system where, once a week, a team member gives a Pecha Kucha talk on any topic to help improve our ability to give presentations.

So I'm thinking of suggesting the writing workshops as well.

Does anyone have writing workshops at their place of work?

"A man who has the knowledge but lacks the power clearly to express it is no better off than if he never had any ideas at all." - Thucydides

Edit: What I am talking about here is the ability to document your code in a clear manner, e.g. tech. spec's and design doc's. Not the writing of the source code itself.

Answer 1

Yes! Most definitely.

One of the biggest problems I see in code is the inability to name things accurately. This can often be down to the inability to express one's ideas.

A great resource to improve writing skills is: The elements of Style. It's small, succinct and easy to read.

Answer 2

What we do is to let co-workers do a presentation every week, mostly on technical topics, so that we also get some advanced training.

I guess this not only trains the ability to express yourself, but it also strengthens the team and the communication within the team.

It really improves productivity if the team members know how to express themselves, even as far as tiny things like the difference between "parameters" and "arguments" are concerned.

Answer 3

my thoughts:

A, The Most important, i think a developer needs to be able to write clear, concise, beautiful, self documenting code. This is far more important than writing docs.

B, Your Unit Tests should also be clear and concise and a form of documentation as to how to use code.

C. Part of this depends. If they are very low level programmers working on smal parts of code, A + B stand, However, if they are high level, or work on a large part of the system, or the whole system, then yes it becomes more imprtant that they know how to write clearly and properly, but to an extent.

In short, I think it is important, but it is not the measure of how good a develper is. How well the code documents itself is the true measure.

Besides if every developer could write docs, then technical writers would be out of a job.

As to do i know any resources or what to suggest, no I dont, i have never really looked to improved my writing capabilities.

EDIT: I should also add though some of this depends on the process you use and what roles and responsibilities a developer might have. Obviously if its required that developers write part of the user manual, then yes, writing clearly is VERY important. But this is not usually the norm.

EDIT2: None of this is meant to say that a devloper should not have ANY writing skills, it was more to say that code writing is far more important than tech/doc writing.

EDIT3: Now that it has been clarified that the OP doesnt want any reference to writing code, then I must say that no, in general it is not very important for a developer to be able to write technical documentation and design documentation, as there are far more important things for a deveoloper to be good at.

Answer 4

Software developers very much like professionals in any other area or industry should be able to express their thoughts and ideas.

Software development is a team effort and communication is single most important factor that can cause project failure. The more so nowadays developers on projects communicate with sales, marketing, business people, users and others how do not have a clue in software development. And ability to communicate ideas and lean others towards them is very critical skill.

Needless to say that if Tech Lead came up with brilliant design but is not able communicate his design to the rest of the team, this means that you have no design.

Answer 5

Here in Argentina we have to communicate with our pals at US to get our work done.

The main way of communication is email and IM. You wouldn't imagine how difficult it is to understand lots and lots of emails because of lack of good writing. And I'm not talking about difficult technical stuff, but just how to express yourself in plain english.

So, yes. I think that it's very important.

Answer 6

@slashmais: Anyone in any sort of professional capacity should be able to communicate clearly, be it engineer, manager, tester or whatever. This isn't just a personal preference, I believe this for the good of an organization or business. You don't want programmers whose only function is to implement and poorly document code; you want engineers who can think deeply about the code and communicate it's intent to others in a medium outside of the code listing.

What we do at my company is a weekly technical presentation by an engineer on a topic of their choice. This is a big win for everyone--it helps the engineer hone their speaking and writing skills and educates us about what they're doing. We also have code reviews where the documentation of the code is critiqued just as much as the code itself. This leads to far more maintainable code.

It doesn't matter if it's IM, email, written documents or code--the less time I have to spend trying to parse your communication and the more time I spend accomplishing things as a result of your communication, the better for my company.

Answer 7

Yes, programmers should document their own work; would you build a house from a one-eighth-scale model and trust that blueprints weren't necessary?

Worth reading: Steve McConnell's Code Complete, especially the chapters on naming functions and writing documentation. If you're naming and commenting your code appropriately, the docs write themselves.

Answer 8

Obligatory Dijkstra quote:

Besides a mathematical inclination, an exceptionally good mastery of one's native tongue is the most vital asset of a competent programmer.

Answer 9

Communication is essential in any profession, software engineering and computer programming are no exceptions. It doesn't matter how brilliant your idea is if you cannot effectively communicate it to your peers, managers, and customers. You can have as much influence with well written text as with well written code.

A good example that I'm sure is familiar to most people reading this is the famous K&R book. In my opinion, one of the reasons that C became such a prominent programming language is because Kernighan and Ritchie produced a well written book. Had they produced a manual that was typical of the style of compiler manuals at the time instead of an easy to follow, succinct, and compete textbook I doubt C would have become as dominant as it has.

Answer 10

The task of programming involves two major parts. The first is communicating to a machine what is that you are trying to do with your code. That is the easy part, the compiler/interpreter/virtual machine does most of the work there. The hard part is communicating to the other programmers what you are trying to do with your code.

Because of the human aspect of programming, it is vital that you are an effective writer to be an effective programmer. Making things work isn't good enough, the people who come after you need to be able to understand it and work with it just as well.

Having good writing skills can help you write code in a more natural language way (although there are pit-falls to natural languages, so use as appropriate). It will also help you document, comment, and explain that code better.

As Blair Conrad said, naming things is also important and is greatly benefited by having better writing skills. What you call things has an impact on the way people think about them. If other programmers can figure out how the code was thought out, then they have a better chance of using that code as intended.

Answer 11

Yes,

But writing clearly is not the same as having faultless spelling and grammar.

However good someone spelling is, their writing will be hard to understand if they can’t order their thoughts in a logical way and decide what details are important to include (and leave out).

A short comment that is to the point is a lot better then a long comment with faultless grammar that does not hit the point.

If you wish to move into management then being able to quickly write long documents with perfect spelling and grammar become a lot more important.

Remember it all about how easy it is someone to understand what you mean, not how match they like your style of writing.

Faultless grammar is not always the best way to communicate, e.g.

“This is the sort of English up with which I will not put.”